Schema

Overview

The Custom Player Model (CPM) JSON allows you to use bones, boxes, planes, ribbons and particles with the functions of expressions to customize your model appearance.

The Main JSON

Each model pack must contain a json file named "model.json". A typical model json seems like:

{
    "hide": [ ... ],	// optional
    "bones": [ ... ]
}

Hidden model parts

The "hide" entry contains all model parts that you want to hide - in case you want to completely change the original look of that part, or want to change their original position. Each element of the array must be one of the original bones:

• head
• head_overlay
• body
• body_overlay
• left_arm
• left_arm_overlay
• right_arm
• right_arm_overlay
• left_leg
• left_leg_overlay
• right_leg
• right_leg_overlay

Or one of the original features:

• helmet_head
• helmet_head_overlay
• chestplate_body
• chestplate_left_arm
• chestplate_right_arm
• leggings_body
• leggings_left_leg
• leggings_right_leg
• boots_left_leg
• boots_right_leg
• held_item_left
• held_item_right
• cape
• head_wearing (skull, carved pumpkin)
• elytra
• shoulder_parrot_left
• shoulder_parrot_right

Or the combination of them:

• head_all: head, head_overlay

• body_all: body, body_overlay

• left_arm_all: left_arm, left_arm_overlay

• right_arm_all: right_arm, right_arm_overlay

• arms_all: left_arm_all, right_arm_all

• left_leg_all: left_leg, left_leg_overlay

• right_leg_all: right_leg, right_leg_overlay

• legs_all: left_leg_all, right_leg_all

• model_all: head_all, body_all, arms_all, legs_all

• helmet_all: helmet_head, helmet_head_overlay

• chestplate_all: chestplate_body, chestplate_left_arm, chestplate_right_arm

• leggings_all: leggings_body, leggings_left_leg, leggings_right_leg

• boots_all: boots_left_leg, boots_right_leg

• armor_body_all: chestplate_body, leggings_body

• armor_arms_all: chestplate_left_arm, chestplate_right_arm

• armor_left_leg_all: leggings_left_leg, boots_left_leg

• armor_right_leg_all: leggings_right_leg, boots_right_leg

• armor_legs_all: armor_left_leg_all, armor_right_leg_all

• armor_all: helmet_all, armor_body_all, armor_arms_all, armor_legs_all

• held_item_all: held_item_left, held_item_right

• shoulder_parrot_all: shoulder_parrot_left, shoulder_parrot_right

• feature_all: armor_all, held_item_all, shoulder_parrot_all, cape, head_wearing, elytra

After hiding them you can attach these features (not bones) to your custom bones to change their original position. The scale / visibility of the bone will also be applied to attached features.

Coordinates

Unlike the original model coordinate system, the one used by CPM is the same as the minecraft world coordinate system, and the player model is facing North, or -Z.

Direction	XYZ
East	+X
West	-X
North	-Z
South	+Z
Up	+Y
Down	-Y

Bones

Bones are the base of each model, they form the skeleton of player models, and define the movement of each part. A typical bone json seems like:

{
    "id": ...,
    "parent": ...,					// optional
    "texture": ...,					// optional, animated
    "textureSize": [ ..., ... ],	// optional
    "position": [ ..., ..., ... ],	// optional, animated
    "rotation": [ ..., ..., ... ],	// optional, animated
    "scale": [ ..., ..., ... ],		// optional, animated
    "visible": ...,					// optional, animated
    "physics": [ ... ],				// optional
    "attached": [ ... ],			// optional
    "boxes": [ ... ],				// optional
    "quads": [ ... ],				// optional
    "particles": [ ... ]			// optional
}

• id: Each bone must have a unique id, and cannot be same as original bones or features (body, head, etc).
• parent: Parent must be one of the original bones, or a custom bone that appears earlier. In other words, parents and children must appears sequentially. Child bones will follow the transformation (texture, position, rotation, scale and visibility) of parent bone, as if it is a part of its parent. If empty, "body" will be chosen as the parent.
• texture: The texture file name with prefix "tex." without path or suffix (e.g. "tex.hair" if your texture file is named "hair.png"). Texture files are stored in the same folder as "model.json". If empty, the original player skin texture will be used if its parent is an original bone, or it will use the same texture as its parent. There are 3 default textures: "tex.skin" for the original skin, "tex.cape" for the player cape if there has one and "tex.elytra" for the elytra texture. For players who do not have capes, use "tex.cape>0" to test whether current player has cape or not.
• textureSize: Must be specified when "texture" is specified. In most cases it is the same as the texture resolution. This is not animated so when you animate the texture, make sure that all textures used have the same resolution.
• position: Define the relative position of children bones. Notice that this does not change the position of current bone. Default value [0, 0, 0].
• rotation: Define the Euler angles (yaw, pitch, roll) of current bone in degrees. Default value [0, 0, 0].
• scale: Define the scale of current bone. Default value [1, 1, 1].
• visible: Weather the visible elements (boxes, quads, particles) are rendered or not. If not specified, it will have the same visibility as its parent.
• physics, boxes, quads & particles: See following section.
• attached: Once you want to change the position of an original feature (armor, held items, etc.), you can hide them and attach them to the new bone. Having the same feature attached to several bones will make the feature render several times.

Boxes & Quads

Most entity models in minecraft are constructed of boxes. A typical box json seems like:

{
    "textureOffset": [ ..., ... ],	// optional
    "coordinates": [ ... ],			// optional
    "sizeAdd": ...					// optional
}

• textureOffset: The top-left corner of the box UV coordinates. Each box contains six faces, and is arranged in the same method as player skins. Default value [0, 0].
• coordinates: Define the offset and the size of the box. First three arguments are the offset, and the next three are the size. Default value [0, 0, 0, 0, 0, 0]. The ratio between box coordinates and actual world coordinates is 16:1.
• sizeAdd: Expand the box just like original skin overlays. Default 0.

Quads jsons are almost the same as boxes, except they are two-dimensional, so "coordinates" only contains 5 arguments.

Particles

Particle system is commonly used in modern 3D games. This mod provides various parameters for particle emitters for you to customize special effects.

{
    "posRange": [ ..., ..., ... ],	// optional, animated
    "dirRange": ...,				// optional, animated
    "angle": [ ..., ... ],			// optional, animated
    "speed": [ ..., ... ],			// optional, animated
    "rotSpeed": [ ..., ... ],		// optional, animated
    "lifeSpan": [ ..., ... ],		// optional, animated
    "density": ...,					// optional, animated
    "animation": [ ..., ... ],		// optional
    "colorR": [ ..., ... ],			// optional, animated
    "colorG": [ ..., ... ],			// optional, animated
    "colorB": [ ..., ... ],			// optional, animated
    "colorA": [ ..., ... ],			// optional, animated
    "size": [ ..., ... ],			// optional, animated
    "gravity": ...,					// optional, animated
    "collide": ...					// optional, animated
}

• posRange: The maximum initial offset for new particles relative to current bone position. Default value [0, 0, 0].
• dirRange: The maximum movement direction angle in degrees when spawning. When 0, new particles will move along the Z-axis of current bone, and will pick up one direction randomly in a circular cone when it is not 0. Default value 0.
• angle: Minimum and maximum value of initial rotation angle in degrees. Default value [0, 0].
• speed: Minimum and maximum value of movement speed in blocks / s. Default value [0, 0].
• rotSpeed: Minimum and maximum value of rotation speed in degrees / s. Default value [0, 0].
• lifeSpan: Minimum and maximum value of how long each particle exists in game ticks. Default value [1, 1].
• density: How many particles are spawned in 1 game tick. Default value 1.
• animation: Textures for particles can be split into sub-images to make animation. This parameter specifies how many sub-images are there each column / row. Default value [1, 1].
• color(R|G|B|A): Minimum and Maximum value of particle color. Default value [1, 1].
• size: Minimum and Maximum value of particle size. Default value [1, 1].
• gravity: If not 0, a constant force with direction -Y will be applied to all particles. Can be negative. Default value 0.
• collide: Whether particles will collide with blocks / entities. Default false.

Physics

The "physics" entry in bone json specifies that current bone is a ribbon. A ribbon will not move along its parent like a rigid body, but will follow physical regulations like a spring, and can be used to simulate the movement of hair, scarf, etc. This entry contains 5 arguments:

• elasticity: [0, +inf), strength of the force applied when parent bone moves, pointing to movement direction.
• stiffness: [0, +inf), strength of the force applied constantly to recover the initial direction relative to the parent bone.
• damping1: [0, 1), multiplies to the velocity of current bone every game tick to simulate damping.
• damping2: [0, +inf), strength of the force applied in the opposite direction of the velocity of player entity.
• gravity: [0, +inf), strength of the gravity.

Animations

CPM enables players to use expressions to create their own animations. For example, the following bone:

{
    "id": "bounce".
    "position": [ 0, "sin(age)", 0 ],
    "boxes": [ ... ]
}

It will bounce constantly in Y axis.

There are two kinds of expressions: float and boolean. They can be combined with various variables and functions to achieve complexed movements. Animation expressions can be applied to all arguments above that are marked "animated".

Following are all the variables and functions that can be used to form expressions:

name	type	arguments	description
limb_swing	float variable		current limb swing angle
limb_speed	float variable		current limb swing amount
age	float variable		age of current player entity
head_yaw	float variable		yaw of head
head_pitch	float variable		pitch of head
scale	float variable		scale of player entity (0.0625)
health	float variable		player health
food_level	float variable		player food level
hurt_time	float variable		remaining time of being hurt (rendered red)
pos_x	float variable		position X
pos_y	float variable		position Y
pos_z	float variable		position Z
speed_x	float variable		velocity X
speed_y	float variable		velocity Y
speed_z	float variable		velocity Z
yaw	float variable		yaw of body
pitch	float variable		pitch of body
swing_progress	float variable		progress of hand swing [0, 1] (attack, place blocks)
is_alive	boolean variable		is player alive
is_burning	boolean variable		is player burning
is_glowing	boolean variable		is player glowing
is_hurt	boolean variable		is in hurt time (rendered red)
is_in_lava	boolean variable		is player in lava
is_in_water	boolean variable		is player in water
is_invisible	boolean variable		is player invisible
is_on_ground	boolean variable		is player on ground
is_riding	boolean variable		is player riding
is_sneaking	boolean variable		is player sneaking
is_sprinting	boolean variable		is player sprinting
is_wet	boolean variable		is player wet (rain, water)
pi	float constant		3.1415926 ...
time	float variable		current day time [0, 24000)
+, -, *, /, %	float function	float x 2	basic calculations
sin, asin, cos, acos, tan, atan	float function	float	trigonometric function
atan2	float function	float x 2	trigonometric function
torad, todeg	float function	float	degree / radian conversion
min, max	float function	float x n	minimum & maximum
clamp	float function	float x 3	max(f2, min(f1, f3))
abs, floor, ceil, exp, frac, log, pow, round, signum, sqrt	float function	float	basic math functions
fmod	float function	float x 2	floor mod
random	float function	-	return a float in [0, 1)
!, &&, ||	boolean function	boolean x 2	boolean operations
>, >=, <, <=, ==, !=	boolean function	float x 2	float comparison
equals	boolean function	float x 3	is abs(f1 - f2) < f3
between	boolean function	float x 3	is f1 between f2 and f3
in	boolean function	float x n	is f1 one of {f2, f3, ..., fn}
if	float function	boolean, float, (boolean, float) x n, float	if (b1) f1 {else if (b2) f2} x n else fn
(bone name).(t|r|s)(x|y|z)	float variable		get the relative position, rotation and scale of specified bone. e.g. head.rx, body.tz, etc.
tex.(texture name)	float variable		get the texture with specified name.
inv.(mainhand|offhand| helmet|chestplate|leggings| boots|main(0 - 35))	float variable		access the inventory of current player. e.g. inv.main4 means the fifth slot of the player inventory.
item.(item id)	float variable		get the id of specified item. e.g. use inv.mainhand==item.apple to check if the player is holding an apple.