Declarative

You will usually create new entities through the alacrity's specs system that makes use of the declarative Lua syntax. Unless you have the need of creating an ad-hoc entity from scratch you will have few to no need of using any other means in order to define and instance entities for your games.

Alacrity Specs

Alacrity specs allow you to define entity spec blueprints through the declarative Lua API. Here's how you can create entities using alacrity specs:

Step One

Create a new Lua spec file in your $ALACRITY_SPECS_PATH/entities

Step Two

Define a Lua table that will represent the new blueprint

local humanMageBlueprint = {
    id = "PC#HUMAN#CLERIC_001",
    name = "Cleric Human Playable Character 001",
    description = "Blueprint defining an Human Cleric playable character",
    tags = {
        -- this is an humanoid type of character 
        { name = "humanoid", value = "human" },
        -- this is a playable character
        { name = "payable_character", value = 1 },
    },
    attributes = {
        { name = "max_hit_point", value = 10 },
        { name = "str", value = 5 },
        { name = "dex", value = 2 },
        { name = "con", value = 6 },
        { name = "int", value = 4 },
        { name = "wis", value = 2 },
        { name = "cha", value = 8 },
        -- add more attributes as needed
    },
    properties = {
        { name = "mental_condition", value = "good" },
        { name = "level", value = 1 },
        { name = "class", value = "cleric" },
        { name = "ftue_completed", value = false, hide_from_conditions = true },
        { name = "current_tracking_quest", value = 0, hide_from_conditions = true },
        { name = "last_check_point", value = "none", hide_from_conditions = true },
        -- add more properties as needed
    },
    buffs = {
        -- this attached buff is defined elsewhere in the specs
        "52e59fb8-0395-4425-a4d5-56d87756491a",
    },
    version = "0.0.1",    
}

Step Three

Add the entity definition to an entities table in the same spec file

local entities = {
    -- Human Cleric PC
    humanMageBlueprint,
}

Step Four

Return the entities table with your entities definitions

return entities

Instantiating the Entity

With our entity in place we can now instantiate it from both Rust or Lua APIs in our game logic as we need.

-- the entity template that we want to instantiate
local entityTemplateID = "PC#HUMAN#CLERIC_001"
 
-- the ID that we want for the entity
local entityID = "6137c461-a3cb-4910-b501-a3db682b36a3"

-- instantiate a new Human Cleric PC entity template with the given ID
local clericEntity, ok = pcall(function() 
    local e = alacrity.Entity.instance(entityTemplateID, entityID)
    return e
end)

if not ok then
    -- handle error
end

Of course we can also instantiate the entity using the Rust API

#![allow(unused)]
fn main() {
let entity_template_id = "PC#HUMAN#CLERIC_001"
let entity_id = "6137c461-a3cb-4910-b501-a3db682b36a3"

let mut e = Entity::new(entity_template_id, Some(entity_id));
match e {
    Ok(e) => {
        // do something with the entity
    },
    Err(e) => {
        // handle error
    }
}
}

Alacrity Book