Basic Entity

From Vintage Story Wiki
Jump to: navigation, search


We highly recommend to read the tutorial Getting Started 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,
            "prority": 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,
            "prority": 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": [ "figure: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


Vintage Story: Modding
Basics Mod Types | Asset System | Textures | Items | Recipes | Blocks | Model Creator | Release
Advanced Setup(Windows,Linux) | Items | Blocks | Item-Block interractions | Block Behavior | Block Entity | Particles | World Access
Worldgen Terrain | Ores | Trees | Worldgen API
Rendering Shaders and Renderers
Property Overview Item | Block | Block Behaviors