Entities

Entities

An entity within Kaetram may refer to any object that the player may interact with. The following are a list of all available entities within the game:

• Player Characters
• Mobs
• NPCs
• Pets
• Items
• Chests
• Projectiles
• Special effects

Amongst these, a subclass called Character indicates entities that can move, perform combat, have status effects, and may interact more actively with the player. The player, mobs, and pets are all subclasses of characters. They may all engage in combat or move around the map.

Adding an entity to the game

Almost all entities follow a similar procedure when being added to the game. First and foremost, you must have the sprite image associated with each entity. For items it is a single 16x16 item image, for the rest it generally consists of a sprite sheet with all the animation frames.

Next you must go to packages/client/data/sprites.json. This is a pretty large file, however I have tried to organize entities into groups, separated by a space. Here you must first provide the path (relative to the sprites folder in packages/client/public/img/sprites). This path is used to separate each sprite into categories (player, npc, mobs, etc.). In the case of player, we also split into sub-categories (helmet, chestplate, legplates, etc.) At the very end of the file, the items are defined. As of recently, we have tried to condense the amount of information in this file by having pre-defined variables for entities that follow the same format across the board. In the case of items, we only provide the path, and the default values are substituted during initialization (i.e. their offsets). Default values can be overriden, here is an example of an entity with all the properties:

    {
        "id": "mobs/beetle",
        "width": 64,
        "height": 72,
        "idleSpeed": 300,
        "animations": {
            "atk_right": {
                "length": 6,
                "row": 0
            },
            "walk_right": {
                "length": 6,
                "row": 1
            },
            "idle_right": {
                "length": 2,
                "row": 2
            },
            "atk_up": {
                "length": 6,
                "row": 3
            },
            "walk_up": {
                "length": 6,
                "row": 4
            },
            "idle_up": {
                "length": 2,
                "row": 5
            },
            "atk_down": {
                "length": 6,
                "row": 6
            },
            "walk_down": {
                "length": 6,
                "row": 7
            },
            "idle_down": {
                "length": 2,
                "row": 8
            }
        },
        "offsetX": -24,
        "offsetY": -54
    },

Breaking it down, this is a list of all the properties and what they mean:

• id - Refers to the path of the image file relative to the sprites image directory. In the above example, the path of the image is packages/client/public/img/sprites/mbos/beetle.png.
• width/height - The width and height of a frame. This is not the same as image dimensions, only a singular frame. You can usually determine this by dividing the width/height by the amount of frames.
• idleSpeed - Override for how fast we want the animation speed when the entity is idling.
• animations - An object dictionary containing animations for each action the entity will perform. Generally for mobs/players/pets, the available list of actions is idle|walk|atk|atk___down|right|up. For the player an additional action for bow_atk was added when using bows. The exat format for each entity can be found in packages/client/src/utils/util.ts in the getDefaultAnimations() function. The length indicates how many frames to iterate through, and the row which row within the sprite sheet to select.
• offsetX/offsetY - These are offset properties that are used to properly position the entity relative to a tile. This is due to the fact that the anchor point of the image is in the upper left corner, so we have to offset the sprite to be centred relative to that. The default is -16 if not specified, unless predefined in getDefaultOffset in the util.ts file.

After having added the entity of your choice to sprites.json (and in the appropriate folder of the sprites), you must next set up its properties if applicable. This is usually the case for items, mobs, and NPCs. We can define their respective file in the server-side. Head over to packages/server/data/ and here you will see mobs.json, npcs.json, and items.json. Pick the appropriate file. Here you can copy one of the existing examples and change the values according to your needs. Note that in the case of items.json, items are usually grouped by helmets, chestplates, legplates, so try to follow that order somewhat. In the case of random miscellaneous items, they are located further down in the file.