API Entities

Entities

Lua API / Entities

betamoon.entities:add(definition) declares a custom entity type during modInit() or modReload() and returns a type reference. kind chooses "prop" (default), "projectile", "living", or "pickup". These types work in local singleplayer worlds and are not synchronized in multiplayer. Entity instances and declared data are saved with the world.

Declare an entity

All kinds require a lowercase namespaced key. displayName is optional. Props, projectiles, and living entities require an appearance with a model and its material textures. A pickup may omit appearance to use its item's native dropped-item rendering, or provide one for a custom model. width and height set the native movement and collision body in blocks (greater than zero, at most 16). Defaults are 0.6 × 1 for props and living entities, and 0.25 × 0.25 for projectiles and pickups. Set body = { targetable = false } to keep this body out of ray and projectile targeting while retaining it for movement and collision. Targeting defaults to true except on pickups.

local lantern = betamoon.entities:add {
    key = "mymod:entity/lantern",
    appearance = {
        model = "mymod:entity/lantern",
        texture = "mymod:entity/lantern"
    },
    onInteract = function(ctx)
        return betamoon.callbackResults.handled
    end
}

Register referenced assets before the entity. Its model, textures, and animation use the same texture-pack override paths as block and item appearances. The appearance accepts clips and onPose for visual animation. See First Entity for a runnable prop.

Entity systems

Each entity type combines only the systems it declares or its kind supports.

Reference	Covers
Entity access and movement	Scoped handles, common queries, movement, targeting, navigation, and entity actions.
Entity lifecycle and data	Lifecycle modes and callbacks, persistent data, transient memory, states, and timers.
Entity health and loot	Health, damage callbacks, death behavior, declared loot, and direct item drops.
Entity inventories and relationships	Inventories, equipment, ownership, teams, mounts, and passengers.
Projectiles and pickups	Specialized projectile and collectible entity kinds.
Entity presentation and sounds	Models, animation, visual transforms, rendering options, and sound bindings.
Living entities and AI	Natural spawning, living properties, AI modes, stages, and navigation.
Entity parts and sensors	Multipart hit/interaction shapes and overlap sensors.

Entity-type lookup

Method	Result
betamoon.entities:get(key)	Type reference, or nil if absent.
betamoon.entities:getRequired(key)	Type reference, or an error if absent.
betamoon.entities:find/first/one(query)	Query by key, owner, and/or kind.

Entity-type reference

References retain their key across script reloads. A removed type cannot be spawned until it is declared again. References also expose live key, owner, exists, kind, displayName, width, height, and tickInterval. type:getKey() returns the exact namespaced key.

type:override(definition)

Overrides non-structural type settings and supported top-level callbacks. Supported definition groups include body, render, sounds, physics, behavior, drops, and the applicable projectile/living/spawning/pickup/health group. Scalar fields include displayName, width, height, and tickInterval. Callback layers use ctx:base().

The entity key/kind, persistent data schemas, inventory/equipment layout, lifecycle ownership, and behavior-state schemas remain structural. Existing instances refresh the effective definition without changing their saved identity.

Explicit spawning

Call ctx.world:spawnEntity(type, options) from a mutable callback. type is a reference or key. options.position is { x, y, z }; optional rotation supplies yaw and pitch in degrees. Projectile types may also receive a live same-world owner handle for owner grace and damage attribution. Supplying owner for another kind raises an error. On success it returns an entity handle valid for the current callback. On placement failure it returns nil, reason ("blocked", "chunk_unloaded", "outside_world", "client_world", or "removed_on_spawn" when onSpawn removes it). Invalid arguments or an unknown type raise an error. Spawning does not load chunks.

local entity, reason = ctx.world:spawnEntity(lantern, {
    position = { x = 10.5, y = 65, z = 20.5 },
    rotation = { yaw = 90 }
})