Skip to main content

Entity

The entity interface

e = Entity.spawn("Slime", 79, 29)
e:move(29, 29, 10, { damage = 10 })
e.dead = true

Player.heal()

See EntityRef for what you can do with entities.

Properties​

player​

</>
Entity.player: EntityRef

Get the player entity

Also available as Player globally.

Entity.player.x = 79
Player.x = 79 -- same effect

persistence​

</>
Entity.persistence: string

Get/Set the active persistence id

Functions​

get​

</>
Entity.get(
x: number,--

horizontal position

y: number--

vertical position

) → EntityRef--

found entity

Retrieve an entity on a position

Warning: Unsuitable for multiple entities on a position

get_all​

</>
Entity.get_all(
x: number,--

horizontal position

y: number--

vertical position

) → ()

Retrieve all entities on a position

persistence_skip​

</>
Entity.persistence_skip() → ()

Skip the persistence slot

new​

</>
Entity.new(
x: number,--

horizontal position

y: number--

vertical position

) → ()

Create a new generic entity

spawn​

</>
Entity.spawn(
factory: string,--

entity factory id

x: number,--

horizontal position

y: number,--

vertical position

options: table | nil--

settings

) → EntityRef--

spawned entity

Spawn entity

The below generic options are available for most other spawn functions too.

Generic Options

Name Type Default Description
flag table - Entity flags table
instrument string - Instrument identifier
fg table - Foreground color
bg table - Background color

Specific Options

Name Type Default Description
func string - Spawn function character

light_circle​

</>
Entity.light_circle(
x: number,--

horizontal position

y: number,--

vertical position

options: table | nil--

settings

) → EntityRef--

spawned entity

Spawn light circle

Specific Options

Name Type Default Description
r number 255 red
g number 255 green
b number 255 blue
offset number 0 time offset for pulse (s)
collision bool false shadows
radius number 8 circle radius
amplitude number 0 pulse amplitude
period number Beat pulse period

light_cone​

</>
Entity.light_cone(
x: number,--

horizontal position

y: number,--

vertical position

options: table | nil--

settings

) → EntityRef--

spawned entity

Spawn light cone

Specific Options

Name Type Default Description
r number 255 red
g number 255 green
b number 255 blue
offset number 0 time offset for pulse (s)
collision bool false shadows
radius number 8 cone radius
angle number 0 cone angle
amplitude number 0 pulse amplitude
period number Beat pulse period
rotation number 0 rotation period

explosion​

</>
Entity.explosion(
x: number,--

horizontal position

y: number,--

vertical position

options: table | nil--

settings

) → EntityRef--

spawned entity

Spawn explosion

Specific Options

Name Type Default Description
instrument string Neutral entity instrument
count number 1 amount of rings
speed number 50 speed of explosion
radius number 4 size of explosion
radius_p number 1 distance p-norm param
damage number 0 amount of damage

laser​

</>
Entity.laser(
x: number,--

horizontal position

y: number,--

vertical position

options: table | nil--

settings

) → EntityRef--

spawned entity

Spawn laser

Specific Options

Name Type Default Description
instrument string Neutral entity instrument
dx number 1 horizontal direction
dy number 1 vertical direction
offset number 0 laser offset
scale number 1 laser scale

text​

</>
Entity.text(
x: number,--

horizontal position

y: number,--

vertical position

options: table | nil--

settings

) → EntityRef--

spawned entity

Spawn text

Specific Options

Name Type Default Description
text string - text to display
font string - text font
center bool true horizontal center
cost bool false special coin cost mode
r number 255 default text color red
g number 255 default text color green
b number 255 default text color blue

image​

</>
Entity.image(
x: number,--

horizontal position

y: number,--

vertical position

options: table | nil--

settings

) → EntityRef--

spawned entity

Spawn image

Specific Options

Name Type Default Description
path string - image path
center bool true horizontal center
collision bool false image collision
r number 255 default image color red
g number 255 default image color green
b number 255 default image color blue

animation​

</>
Entity.animation(
x: number,--

horizontal position

y: number,--

vertical position

options: table | nil--

settings

) → EntityRef

Spawn animation

Specific Options

Name Type Default Description
path string - animation path
duration number Beat animation frame duration (s)
oneshot bool false play once and kill entity
sync bool false synchronize animation to music
background bool true show in background
r number 255 default animation color red
g number 255 default animation color green
b number 255 default animation color blue

window​

</>
Entity.window(
x: number,--

horizontal position

y: number,--

vertical position

options: table | nil--

settings

) → EntityRef--

spawned entity

Spawn window

Specific Options

Name Type Default Description
direction string - window direction (e.g. "up")
r number 255 default animation color red
g number 255 default animation color green
b number 255 default animation color blue

skin​

</>
Entity.skin(
x: number,--

horizontal position

y: number,--

vertical position

options: table | nil--

settings

) → EntityRef--

spawned entity

Spawn skin

Specific Options

Name Type Default Description
skin string - entity skin id
collision bool true entity collision

spawner​

</>
Entity.spawner(
x: number,--

horizontal position

y: number,--

vertical position

options: table | nil--

settings

) → EntityRef--

spawned entity

Spawn spawner

Specific Options

Name Type Default Description
rate number Beat spawn delay (s)
factory string - entity factory id
instrument string Neutral entity instrument
ch string - spawner character
function_self string - spawner function char
function_spawn string - spawned entity function char

item​

</>
Entity.item(
x: number,--

horizontal position

y: number,--

vertical position

options: table | nil--

settings

) → EntityRef--

spawned entity

Spawn item

Specific Options

Name Type Default Description
type string - item type identifier
level number 0 item level
id string - item custom identifier
Show raw api
{
    "functions": [
        {
            "name": "get",
            "desc": "Retrieve an entity on a position\n\n**Warning**: Unsuitable for multiple entities on a position",
            "params": [
                {
                    "name": "x",
                    "desc": "horizontal position",
                    "lua_type": "number"
                },
                {
                    "name": "y",
                    "desc": "vertical position",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "found entity",
                    "lua_type": "EntityRef"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 25,
                "path": "../../res/data/script/lib/system/entity.lua"
            }
        },
        {
            "name": "get_all",
            "desc": "Retrieve all entities on a position",
            "params": [
                {
                    "name": "x",
                    "desc": "horizontal position",
                    "lua_type": "number"
                },
                {
                    "name": "y",
                    "desc": "vertical position",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 34,
                "path": "../../res/data/script/lib/system/entity.lua"
            }
        },
        {
            "name": "persistence_skip",
            "desc": "Skip the persistence slot",
            "params": [],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 62,
                "path": "../../res/data/script/lib/system/entity.lua"
            }
        },
        {
            "name": "new",
            "desc": "Create a new generic entity",
            "params": [
                {
                    "name": "x",
                    "desc": "horizontal position",
                    "lua_type": "number"
                },
                {
                    "name": "y",
                    "desc": "vertical position",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 70,
                "path": "../../res/data/script/lib/system/entity.lua"
            }
        },
        {
            "name": "spawn",
            "desc": "Spawn entity\n\nThe below generic options are available for most other spawn functions too.\n\n### Generic Options\n| Name            | Type        | Default | Description                    |\n|-----------------|-------------|---------|--------------------------------|\n| flag            | table       |       - | Entity flags table             |\n| instrument      | string      |       - | Instrument identifier          |\n| fg              | table       |       - | Foreground color               |\n| bg              | table       |       - | Background color               |\n\n### Specific Options\n| Name            | Type        | Default | Description                    |\n|-----------------|-------------|---------|--------------------------------|\n| func            | string      |       - | Spawn function character       |",
            "params": [
                {
                    "name": "factory",
                    "desc": "entity factory id",
                    "lua_type": "string"
                },
                {
                    "name": "x",
                    "desc": "horizontal position",
                    "lua_type": "number"
                },
                {
                    "name": "y",
                    "desc": "vertical position",
                    "lua_type": "number"
                },
                {
                    "name": "options",
                    "desc": "settings",
                    "lua_type": "table | nil"
                }
            ],
            "returns": [
                {
                    "desc": "spawned entity",
                    "lua_type": "EntityRef"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 97,
                "path": "../../res/data/script/lib/system/entity.lua"
            }
        },
        {
            "name": "light_circle",
            "desc": "Spawn light circle\n\n### Specific Options\n| Name            | Type        | Default | Description                    |\n|-----------------|-------------|---------|--------------------------------|\n| r               | number      |     255 | red                            |\n| g               | number      |     255 | green                          |\n| b               | number      |     255 | blue                           |\n| offset          | number      |       0 | time offset for pulse (s)      |\n| collision       | bool        |   false | shadows                        |\n| radius          | number      |       8 | circle radius                  |\n| amplitude       | number      |       0 | pulse amplitude                |\n| period          | number      |    Beat | pulse period                   |",
            "params": [
                {
                    "name": "x",
                    "desc": "horizontal position",
                    "lua_type": "number"
                },
                {
                    "name": "y",
                    "desc": "vertical position",
                    "lua_type": "number"
                },
                {
                    "name": "options",
                    "desc": "settings",
                    "lua_type": "table | nil"
                }
            ],
            "returns": [
                {
                    "desc": "spawned entity",
                    "lua_type": "EntityRef"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 121,
                "path": "../../res/data/script/lib/system/entity.lua"
            }
        },
        {
            "name": "light_cone",
            "desc": "Spawn light cone\n\n### Specific Options\n| Name            | Type        | Default | Description                    |\n|-----------------|-------------|---------|--------------------------------|\n| r               | number      |     255 | red                            |\n| g               | number      |     255 | green                          |\n| b               | number      |     255 | blue                           |\n| offset          | number      |       0 | time offset for pulse (s)      |\n| collision       | bool        |   false | shadows                        |\n| radius          | number      |       8 | cone radius                    |\n| angle           | number      |       0 | cone angle                     |\n| amplitude       | number      |       0 | pulse amplitude                |\n| period          | number      |    Beat | pulse period                   |\n| rotation        | number      |       0 | rotation period                |",
            "params": [
                {
                    "name": "x",
                    "desc": "horizontal position",
                    "lua_type": "number"
                },
                {
                    "name": "y",
                    "desc": "vertical position",
                    "lua_type": "number"
                },
                {
                    "name": "options",
                    "desc": "settings",
                    "lua_type": "table | nil"
                }
            ],
            "returns": [
                {
                    "desc": "spawned entity",
                    "lua_type": "EntityRef"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 147,
                "path": "../../res/data/script/lib/system/entity.lua"
            }
        },
        {
            "name": "explosion",
            "desc": "Spawn explosion\n\n### Specific Options\n| Name            | Type        | Default | Description                    |\n|-----------------|-------------|---------|--------------------------------|\n| instrument      | string      | Neutral | entity instrument              |\n| count           | number      |       1 | amount of rings                |\n| speed           | number      |      50 | speed of explosion             |\n| radius          | number      |       4 | size of explosion              |\n| radius_p        | number      |       1 | distance p-norm param          |\n| damage          | number      |       0 | amount of damage               |",
            "params": [
                {
                    "name": "x",
                    "desc": "horizontal position",
                    "lua_type": "number"
                },
                {
                    "name": "y",
                    "desc": "vertical position",
                    "lua_type": "number"
                },
                {
                    "name": "options",
                    "desc": "settings",
                    "lua_type": "table | nil"
                }
            ],
            "returns": [
                {
                    "desc": "spawned entity",
                    "lua_type": "EntityRef"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 169,
                "path": "../../res/data/script/lib/system/entity.lua"
            }
        },
        {
            "name": "laser",
            "desc": "Spawn laser\n\n### Specific Options\n| Name            | Type        | Default | Description                    |\n|-----------------|-------------|---------|--------------------------------|\n| instrument      | string      | Neutral | entity instrument              |\n| dx              | number      |       1 | horizontal direction           |\n| dy              | number      |       1 | vertical direction             |\n| offset          | number      |       0 | laser offset                   |\n| scale           | number      |       1 | laser scale                    |",
            "params": [
                {
                    "name": "x",
                    "desc": "horizontal position",
                    "lua_type": "number"
                },
                {
                    "name": "y",
                    "desc": "vertical position",
                    "lua_type": "number"
                },
                {
                    "name": "options",
                    "desc": "settings",
                    "lua_type": "table | nil"
                }
            ],
            "returns": [
                {
                    "desc": "spawned entity",
                    "lua_type": "EntityRef"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 190,
                "path": "../../res/data/script/lib/system/entity.lua"
            }
        },
        {
            "name": "text",
            "desc": "Spawn text\n\n### Specific Options\n| Name            | Type        | Default | Description                    |\n|-----------------|-------------|---------|--------------------------------|\n| text            | string      |       - | text to display                |\n| font            | string      |       - | text font                      |\n| center          | bool        |    true | horizontal center              |\n| cost            | bool        |   false | special coin cost mode         |\n| r               | number      |     255 | default text color red         |\n| g               | number      |     255 | default text color green       |\n| b               | number      |     255 | default text color blue        |",
            "params": [
                {
                    "name": "x",
                    "desc": "horizontal position",
                    "lua_type": "number"
                },
                {
                    "name": "y",
                    "desc": "vertical position",
                    "lua_type": "number"
                },
                {
                    "name": "options",
                    "desc": "settings",
                    "lua_type": "table | nil"
                }
            ],
            "returns": [
                {
                    "desc": "spawned entity",
                    "lua_type": "EntityRef"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 213,
                "path": "../../res/data/script/lib/system/entity.lua"
            }
        },
        {
            "name": "image",
            "desc": "Spawn image\n\n### Specific Options\n| Name            | Type        | Default | Description                    |\n|-----------------|-------------|---------|--------------------------------|\n| path            | string      |       - | image path                     |\n| center          | bool        |    true | horizontal center              |\n| collision       | bool        |   false | image collision                |\n| r               | number      |     255 | default image color red        |\n| g               | number      |     255 | default image color green      |\n| b               | number      |     255 | default image color blue       |",
            "params": [
                {
                    "name": "x",
                    "desc": "horizontal position",
                    "lua_type": "number"
                },
                {
                    "name": "y",
                    "desc": "vertical position",
                    "lua_type": "number"
                },
                {
                    "name": "options",
                    "desc": "settings",
                    "lua_type": "table | nil"
                }
            ],
            "returns": [
                {
                    "desc": "spawned entity",
                    "lua_type": "EntityRef"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 235,
                "path": "../../res/data/script/lib/system/entity.lua"
            }
        },
        {
            "name": "animation",
            "desc": "Spawn animation\n\n### Specific Options\n| Name            | Type        | Default | Description                    |\n|-----------------|-------------|---------|--------------------------------|\n| path            | string      |       - | animation path                 |\n| duration        | number      |    Beat | animation frame duration (s)   |\n| oneshot         | bool        |   false | play once and kill entity      |\n| sync            | bool        |   false | synchronize animation to music |\n| background      | bool        |    true | show in background             |\n| r               | number      |     255 | default animation color red    |\n| g               | number      |     255 | default animation color green  |\n| b               | number      |     255 | default animation color blue   |",
            "params": [
                {
                    "name": "x",
                    "desc": "horizontal position",
                    "lua_type": "number"
                },
                {
                    "name": "y",
                    "desc": "vertical position",
                    "lua_type": "number"
                },
                {
                    "name": "options",
                    "desc": "settings",
                    "lua_type": "table | nil"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "EntityRef"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 259,
                "path": "../../res/data/script/lib/system/entity.lua"
            }
        },
        {
            "name": "window",
            "desc": "Spawn window\n\n### Specific Options\n| Name            | Type        | Default | Description                    |\n|-----------------|-------------|---------|--------------------------------|\n| direction       | string      |       - | window direction (e.g. \"up\")   |\n| r               | number      |     255 | default animation color red    |\n| g               | number      |     255 | default animation color green  |\n| b               | number      |     255 | default animation color blue   |",
            "params": [
                {
                    "name": "x",
                    "desc": "horizontal position",
                    "lua_type": "number"
                },
                {
                    "name": "y",
                    "desc": "vertical position",
                    "lua_type": "number"
                },
                {
                    "name": "options",
                    "desc": "settings",
                    "lua_type": "table | nil"
                }
            ],
            "returns": [
                {
                    "desc": "spawned entity",
                    "lua_type": "EntityRef"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 279,
                "path": "../../res/data/script/lib/system/entity.lua"
            }
        },
        {
            "name": "skin",
            "desc": "Spawn skin\n\n### Specific Options\n| Name            | Type        | Default | Description                    |\n|-----------------|-------------|---------|--------------------------------|\n| skin            | string      |       - | entity skin id                 |\n| collision       | bool        |    true | entity collision               |",
            "params": [
                {
                    "name": "x",
                    "desc": "horizontal position",
                    "lua_type": "number"
                },
                {
                    "name": "y",
                    "desc": "vertical position",
                    "lua_type": "number"
                },
                {
                    "name": "options",
                    "desc": "settings",
                    "lua_type": "table | nil"
                }
            ],
            "returns": [
                {
                    "desc": "spawned entity",
                    "lua_type": "EntityRef"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 297,
                "path": "../../res/data/script/lib/system/entity.lua"
            }
        },
        {
            "name": "spawner",
            "desc": "Spawn spawner\n\n### Specific Options\n| Name            | Type        | Default | Description                    |\n|-----------------|-------------|---------|--------------------------------|\n| rate            | number      |    Beat | spawn delay (s)                |\n| factory         | string      |       - | entity factory id              |\n| instrument      | string      | Neutral | entity instrument              |\n| ch              | string      |       - | spawner character              |\n| function_self   | string      |       - | spawner function char          |\n| function_spawn  | string      |       - | spawned entity function char   |",
            "params": [
                {
                    "name": "x",
                    "desc": "horizontal position",
                    "lua_type": "number"
                },
                {
                    "name": "y",
                    "desc": "vertical position",
                    "lua_type": "number"
                },
                {
                    "name": "options",
                    "desc": "settings",
                    "lua_type": "table | nil"
                }
            ],
            "returns": [
                {
                    "desc": "spawned entity",
                    "lua_type": "EntityRef"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 319,
                "path": "../../res/data/script/lib/system/entity.lua"
            }
        },
        {
            "name": "item",
            "desc": "Spawn item\n\n### Specific Options\n| Name            | Type        | Default | Description                    |\n|-----------------|-------------|---------|--------------------------------|\n| type            | string      |       - | item type identifier           |\n| level           | number      |       0 | item level                     |\n| id              | string      |       - | item custom identifier         |",
            "params": [
                {
                    "name": "x",
                    "desc": "horizontal position",
                    "lua_type": "number"
                },
                {
                    "name": "y",
                    "desc": "vertical position",
                    "lua_type": "number"
                },
                {
                    "name": "options",
                    "desc": "settings",
                    "lua_type": "table | nil"
                }
            ],
            "returns": [
                {
                    "desc": "spawned entity",
                    "lua_type": "EntityRef"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 338,
                "path": "../../res/data/script/lib/system/entity.lua"
            }
        }
    ],
    "properties": [
        {
            "name": "player",
            "desc": "Get the player entity\n\nAlso available as `Player` globally.\n\n```lua\nEntity.player.x = 79\nPlayer.x = 79 -- same effect\n```",
            "lua_type": "EntityRef",
            "source": {
                "line": 50,
                "path": "../../res/data/script/lib/system/entity.lua"
            }
        },
        {
            "name": "persistence",
            "desc": "Get/Set the active persistence id",
            "lua_type": "string",
            "source": {
                "line": 57,
                "path": "../../res/data/script/lib/system/entity.lua"
            }
        }
    ],
    "types": [],
    "name": "Entity",
    "desc": "The entity interface\n\n```lua\ne = Entity.spawn(\"Slime\", 79, 29)\ne:move(29, 29, 10, { damage = 10 })\ne.dead = true\n\nPlayer.heal()\n```\n\nSee [EntityRef](EntityRef) for what you can do with entities.",
    "source": {
        "line": 15,
        "path": "../../res/data/script/lib/system/entity.lua"
    }
}