Modding:Basic Entity

This page was last verified for Vintage Story version uknown.

We highly recommend to read about domains first. This tutorial will cover the basics of adding an entity to the game using JSON files. There is a full list of all properties which can be defined inside the json file here .

Little Figure

The idea is create a little passive figure, made out of wood. The modid of our mod will be figure.

EntityType

Common

So first of all we have to create the entity type file assets/figure/entities/land/littlefigure.json. Now we go through all the properties:

code: The unique identifier for your entity. A prefix of your mod id will be added automatically. Our case its figure:littlefigure.

class: The class of the entity, it can be used to program special features for it. We don't need it at the moment, so we set it to EntityAgent.

hitboxSize: The size of the hitbox.

  "hitboxSize": {
    "x": 0.4,
    "y": 0.5
  },

deadHitboxSize: The size of the hitbox when the entity has died.

  "deadHitboxSize": {
    "x": 0.4,
    "y": 0.5
  },

eyeHeight: The height of the eyes, which is 0.4 for the little figure.

drops: A list of items to be dropped (can also include chances). We leave it empty for now: [].

sounds: Set the sounds for the entity

    "hurt": "creature/figure-hurt",
    "death": "creature/figure-death",
    "idle": "creature/figure-idle"

Client

The client type has different properties for client and server. This will cover the client side (rendering, shape, texture)

(please note that // comments are actually not a valid json syntax, so if you want to use this json code in your projects, you'd have to remove these first)

  "client": {
    "renderer": "Shape", // How the entity will be rendered, "Shape" is the right one in almost all cases.
    "shape": { "base": "entity/land/littlefigure" }, // a path to our shape
    "texture": { "base": "game:block/wood/planks/birch1" }, // the figure should have the texture of birch wood. Therefore the prefix "game" is needed
    "behaviors": [
      { "code": "repulseagents" },
      {
        "code": "controlledphysics", // Adds physics to the entity
        "stepHeight": 0.2
      },
      {
        "code": "floatupwhenstuck", // Fixes corpse get stuck in ground
        "onlyWhenDead": true
      },
      { "code": "interpolateposition" } // Smooths out movement of entity
    ],
    "animations": [ // Animations which have to be implemented by the shape as well
      {
        "code": "hurt",
        "animation": "hurt",
        "animationSpeed": 2.2,
        "weight": 10,
        "blendMode": "AddAverage"
      },
      {
        "code": "die",
        "animation": "die",
        "animationSpeed": 1.25,
        "weight": 10,
        "blendMode": "AddAverage"
      }
    ]
  },

Server

The server side handles the "brain" of the entity.

  "server": {
    "behaviors": [
      { "code": "repulseagents" },
      {
        "code": "controlledphysics", // Adds physic interaction
        "stepHeight": 0.2
      },
      {
        "code": "health", // Adds a health bar to the entity
        "currenthealth": 4,
        "maxhealth": 4
      },
      {
        "code": "deaddecay", // Makes the dead entity stay for one hour
        "hoursToDecay": 1
      },
      {
        "code": "floatupwhenstuck", // Fixes corpse get stuck in ground
        "onlyWhenDead": true
      },
      {
        "code": "despawn", // Makes the entity despawn if there is no player within 48 blocks
        "minPlayerDistance": 48,
        "minSeconds": 5
      },
      {
        "code": "emotionstates", // Adds different emotion states
        "states": [
          {
            "code": "fleeondamage", // After the entity is hit it will try to flee for 10 seconds
            "duration": 10,
            "chance": 0.2,
            "slot": 0,
            "priority": 1,
            "accumType": "max"
          }
        ]
      },
      {
        "code": "taskai", // Handles what the entity does, a task will be processed one at a time
        "aitasks": [
          {
            "code": "idle", // the figure will stand still and think
            "priority": 1.2,
            "priorityForCancel": 1.35,
            "minduration": 4000,
            "maxduration": 6000,
            "chance": 0.001,
            "initialMinCoolDown": 2000,
            "initialMaxCoolDown": 150000,
            "mincooldown": 300000,
            "maxcooldown": 10000000,
            "animation": "think",
            "animationSpeed": 1.25
          },
          {
            "code": "wander", // The entity will walk around
            "priority": 1.0,
            "movespeed": 0.008,
            "animationSpeed": 1.6,
            "animation": "run",
            "preferredLightLevel": 15
          },
          {
            "code": "lookaround", // The entity will look around
            "priority": 0.5
          }
        ]
      }
    ]
  },

Result

If we put everything together it should look like this:

{
  "code": "littlefigure",
  "class": "EntityAgent",
  "hitboxSize": {
    "x": 0.4,
    "y": 0.5
  },
  "deadHitboxSize": {
    "x": 0.4,
    "y": 0.5
  },
  "eyeHeight": 0.4,
  "drops": [],
  "client": {
    "renderer": "Shape",
    "shape": { "base": "entity/land/littlefigure" },
    "texture": { "base": "game:block/wood/planks/birch1" },
    "behaviors": [
      { "code": "repulseagents" },
      {
        "code": "controlledphysics",
        "stepHeight": 0.2
      },
      {
        "code": "floatupwhenstuck",
        "onlyWhenDead": true
      },
      { "code": "interpolateposition" }
    ],
    "animations": [
      {
        "code": "hurt",
        "animation": "hurt",
        "animationSpeed": 2.2,
        "weight": 10,
        "blendMode": "AddAverage"
      },
      {
        "code": "die",
        "animation": "die",
        "animationSpeed": 1.25,
        "weight": 10,
        "blendMode": "AddAverage"
      }
    ]
  },
  "server": {
    "behaviors": [
      { "code": "repulseagents" },
      {
        "code": "controlledphysics",
        "stepHeight": 0.2
      },
      {
        "code": "health",
        "currenthealth": 4,
        "maxhealth": 4
      },
      {
        "code": "deaddecay",
        "hoursToDecay": 1
      },
      {
        "code": "floatupwhenstuck",
        "onlyWhenDead": true
      },
      {
        "code": "despawn",
        "minPlayerDistance": 48,
        "minSeconds": 5
      },
      {
        "code": "emotionstates",
        "states": [
          {
            "code": "fleeondamage",
            "duration": 10,
            "chance": 0.2,
            "slot": 0,
            "priority": 1,
            "accumType": "max"
          }
        ]
      },
      {
        "code": "taskai",
        "aitasks": [
          {
            "code": "idle",
            "priority": 1.2,
            "priorityForCancel": 1.35,
            "minduration": 4000,
            "maxduration": 6000,
            "chance": 0.001,
            "initialMinCoolDown": 2000,
            "initialMaxCoolDown": 150000,
            "mincooldown": 300000,
            "maxcooldown": 10000000,
            "animation": "think",
            "animationSpeed": 1.25
          },
          {
            "code": "wander",
            "priority": 1.0,
            "movespeed": 0.008,
            "animationSpeed": 1.6,
            "animation": "run",
            "preferredLightLevel": 15
          },
          {
            "code": "lookaround",
            "priority": 0.5
          }
        ]
      }
    ]
  },
  "sounds": {
    "hurt": "creature/figure-hurt",
    "death": "creature/figure-death",
    "idle": "creature/figure-idle"
  }
}

Shape

If you want to know how to create the shape for the entity I suggest you checkout VS Model Creator.

Item

In order to spawn the entity we can create an item to do so:

{
  "code": "creature",
  "class": "ItemCreature",
  "maxstacksize": 64,
  "variantgroups": [
    {
      "code": "type",
      "states": [ "littlefigure" ]
    }
  ],
  "shape": {
    "base": "figure:entity/land/littlefigure"
  },
  "texture": { "base": "game:block/wood/planks/birch1" },
  "creativeinventory": {
    "general": [ "*" ],
    "items": [ "*" ],
    "creatures": [ "*" ]
  },
  "materialDensity": 600,
  "guiTransform": {
    "rotation": {
      "x": 0,
      "y": -90,
      "z": -180
    },
    "origin": {
      "x": 0.5,
      "y": 0.15,
      "z": 0.5
    },
    "scale": 6
  },
  "fpHandTransform": {
    "rotation": {
      "x": 0,
      "y": -90,
      "z": 0
    },
    "origin": {
      "x": 0.5,
      "y": 0.15,
      "z": 0.5
    },
    "scale": 6
  },
  "groundTransform": {
    "translation": {
      "x": 0,
      "y": 0.15,
      "z": 0
    },
    "rotation": {
      "x": 0,
      "y": -90,
      "z": 0
    },
    "origin": {
      "x": 0.5,
      "y": 0.15,
      "z": 0.5
    },
    "scale": 6
  }
}

Testing/ Distribution

Download Figure v1.0.0 for VintageStory 1.8

Wondering where some links have gone?
The modding navbox is going through some changes! Check out Navigation Box Updates for more info and help finding specific pages.