Model

The Custom Model API allows you to add non-player models (like NPCs, animals, or other interactive objects) to the entity cache. Once added, these models are treated like native players.

This is useful for creating custom scripts for games with unique PVE elements or interactive environments.

entity.AddModel(string: key, table: data)

Adds a new model to the entity cache. If a model with the same key already exists, it will be overwritten.

Parameter	Type	Description
key	string	A unique identifier for this model (e.g., "npc_1", "guard_tower").
data	table	A table containing the model's properties (see Data Table Fields below).

Returns: boolean - true if successful.

---

entity.RemoveModel(string: key)

Removes a model from the entity cache using its unique key.

Parameter	Type	Description
key	string	The unique identifier of the model to remove.

Returns: boolean - true if a model was successfully removed.

---

entity.ClearModels()

Removes all custom models that were added via AddModel. This is useful for script cleanup or when changing places.

Returns: boolean - true if successful.

---

Data Table Fields

The data table passed to AddModel and EditModel can contain the following fields:

Field	Type	Required	Description
Character	Instance	Yes	The Roblox Model instance to be tracked.
PrimaryPart	Instance	Yes	The root part of the model, used for positioning (e.g., HumanoidRootPart).
Name	string	Yes	A name for the entity (e.g., "Guard", "Zombie").
DisplayName	string	No	A display name. If omitted, falls back to Name.
Team	string	No	The team name for friendly/enemy checks.
Weapon	string	No	The name of the weapon the model is holding.
Humanoid	Humanoid	No	Humanoid Instance, will automatically be used to get health, max health, and move direction/player states.
HealthInstance	Instance	No	(Recommended) An instance of a NumberValue, or IntValue for dynamic, real-time health updates. If you added a Humanoid, you might not need this.
Health	number	No	A static health value. This is only used if HealthInstance or Humanoidis not provided.
MaxHealth	number	No	The maximum health. Required if using static Health or a NumberValue/IntValue.

---

Examples

This example adds an NPC with a Humanoid object. The API will automatically track its health, max health, and velocity in real-time.

local npc_model = game.GetWorkspace():FindFirstChild("GuardNPC")

if npc_model and npc_model:IsA("Model") then
    local humanoid = npc_model:FindFirstChildOfClass("Humanoid")

    if humanoid then
        local npc_data = {
            Character = npc_model,
            PrimaryPart = npc_model.PrimaryPart or npc_model.Head,
            Name = "GuardNPC",
            DisplayName = "Castle Guard",
            Team = "CastleDefenders",
            Humanoid = humanoid -- The API will handle everything from here
        }
        
        -- Add the NPC with a unique key
        entity.AddModel("guard_1", npc_data)
    end
end
-- profit

---

This example adds a "turret" with static health. It won't update automatically, so you must use EditModel to change its health. This is ideal for objects without a Humanoid or NumberValue.

local turret = game.GetWorkspace():FindFirstChild("Turret")

if turret then
    local turret_data = {
        Character = turret,
        PrimaryPart = turret.Base,
        Name = "AutoTurret",
        Team = "Red",
        Health = 500,
        MaxHealth = 500
    }
    entity.AddModel("turret_alpha", turret_data)
end

-- To update its health after it takes damage:
-- entity.EditModel("turret_alpha", { Health = 400 })