Modding:Lua/Starbound Datatypes

From Starbounder - Starbound Wiki
Jump to: navigation, search

Starbound makes extensive use of Lua and JSON, and their data types. There are some types that could use some small amount of documentation, and that is the goal of this page.

Note that a JSON array and a Lua array aren't the same. This post and the following ones give some beginner-level differentiation.


These are integers, not to be confused with callable script objects.


Returned by functions requiring asynchronous data, such as world.sendEntityMessage(). When called locally, it is synchronous. It has four methods that can be called to determine its status:

  • RpcPromiseVariable:finished() returns a boolean indicating whether the promise has finished.
  • RpcPromiseVariable:succeeded() returns a boolean indicating whether the promise has succeeded.
  • RpcPromiseVariable:result() returns the return value(s) of the called function
  • RpcPromiseVariable:error() returns the error string, or nil if no error occured. (Internal radio messages (eg. sendRadioMessage) always return an error, even if they executed properly)

  • LiquidLevel

    Simple array of two values (not an object) returned by various world functions.

    • int liquidId
    • float amount

    The liquid ID (at index 1) corresponds to the numeric liquidId given in the /liquid/*.liquid files (water.liquid is 1, lava.liquid is 2, poison.liquid is 3, etc.). The amount (at index 2) is a floating point range from 0.0 to 1.0 and represents the percentage of liquid filling the space of the tile(s) where the liquid was checked/destroyed.


    JSON object which contains key-value pairs for name and amount, as well as additional parameters:

    • string name
    • int count
    • JSON parameters

    If count or parameters is omitted, it seems they'll be considered as 1 and {} respectively.

    Map<EntityId, unsigned>

    This bears some small note, to prevent potential confusion. It is a Lua table, not an explicit key-value pair.


    Returned from widget.itemGridItems(String widgetName).
    ItemBag is a key-value table of ItemDescriptors.

    Vec2I and Vec2F

    Table which consists of x and y coordinates, returned as a pair of Integers or Floats.

    rectF and rectI

    Json array which contains the top right and bottom left's X and Y coordinates of a rectangle. "I" is for Integer, "F" is for "Float"

    [-1, -1, 1, 1]


    Json array which contains sets of X, Y coordinates forming a polygon's corners. Points are connected in the order of the array with the last point connecting back to the first. In 2D geometry this will always yield a well-defined "inside" but may still provide undesired results if the order of the points is incorrect. For example four points A, B, C, D at the corners of a rectangle will produce an hourglass shape if ordered A, B, D, C instead.

    [ [-0.75, -2.0], [-0.35, -2.5], [0.35, -2.5], [0.75, -2.0], [0.75, 0.65], [0.35, 1.22], [-0.35, 1.22], [-0.75, 0.65] ]


    Denotes the required harvest level of a tile, or the current harvest level of a mining tool. 0 means that the tool doesn't drop anything it mines. All tools have this set at 99, and ores have this set at small amounts, defined by their tier.


    Case-insensitive string used to define things like who can damage who. Vanilla types:

    • friendly: (players, non-agressive NPCs, pets...)
    • enemy: (monsters, agressive NPCs...)
    • passive: (critters...)
    • ghostly: Cannot be hit, unaffected by terrain hazards
    • assistant: (Glitch mission's castle friendly NPC (castle archers, nuru...))
    • environment: (volcanic trap...)
    • indiscriminate: able to hit anything regardless of their damageTeam (traps...)
    • pvp: pvp-enabled players

    damageType and tileDamageType

    Case-insensitive string:

    • blockish: damages blocks
    • plantish: damages plants
    • beamish: Used by the pickslash weaponability
    • explosive: Used by the meteor explosions
    • fire: Damages plants and wooden blocks
    • tilling:
    • damage: Basic damage to everything
    • knockback: Used by shields
    • Environment:
    • IgnoresDef: Ignores the target's protection stat
    • NoDamage: Doesn't do any damage directly. Used by explosive projectiles


    Damage sources from the /damage/ folder. Contain elemental type and hit sounds and particles.

    acid, applystatus, axe, bite, bow, brain, breath, broadsword, bubble, bugnet, capture, dagger, default, direct, electric, electricaxe, electricbarrier, electricbow, electricbroadsword, electricdagger, electricfist, electrichammer, electricplasma, electricplasmabullet, electricplasmashotgun, electricshortsword, electricspear, electrobaton, falling, fire, fireaxe, firebarrier, firebow, firebroadsword, firedagger, firehammer, fireplasma, fireplasmabullet, fireplasmashotgun, fireshortsword, firespear, fishing, fist, fiststrong, flamethrower, foldingchair, fryingpan, gnomebeam, gnomesmack, hammer, heat, hidden, hunger, ice, iceaxe, icebarrier, icebow, icebroadsword, icedagger, icehammer, iceplasma, iceplasmabullet, iceplasmashotgun, iceshortsword, icespear, impact, lash, nodamage, plasma, plasmabullet, plasmashotgun, poison, poisonaxe, poisonbarrier, poisonbow, poisonbroadsword, poisonbullet, poisondagger, poisonhammer, poisonlash, poisonplasma, poisonplasmabullet, poisonplasmashotgun, poisonshortsword, poisonspear, retro, sawblade, shield, shortsword, shotgunbullet, slash, snowball, spear, standardbullet, tarball


    An arbitrary string. Used together with damageRepeatTimeout so that the entity cannot be damaged by the same hitbox every frame.

    monsterfire, crystalbossbeam, shockhopper-flamethrower, npcTouchKnockback, largefloorspike, smallfloorspike, guardiandamagebuff

    Weapons build their own with

    activeItem.ownerEntityId() .. config.getParameter("itemName") .. activeItem.hand() .. mode

    Where "mode" is one of

    primary, alt, hold


    JSON object which contains:

    • string type
    • int team

    type = teamType above. team is used to differentiate multiple groups of the same type.

    {type = "enemy", team = 2}


    JSON object which contains:

    • List<PolyF> poly or
    • List<PolyF> line,
    • int damage,
    • boolean trackSourceEntity,
    • EntityId sourceEntity,
    • DamageTeam team,
    • string damageType,
    • string damageSourceKind,
    • object statusEffects,
    • int knockback,
    • boolean rayCheck,
    • int damageRepeatTimeout,
    • string damageRepeatGroup
        "poly" : [ [-0.75, 0.5], [0.0, 8.0], [0.75, 0.5] ],
        "damage" : 5,
        "teamType" : "friendly",
        "damageType" : "IgnoresDef",
        "damageSourceKind" : "axe",
        "damageRepeatTimeout" : 10,
        "damageRepeatGroup" : "largefloorspike"


    JSON object which contains at least:

    • string damageType,
    • int damage or damageDealt,
    • entityId sourceEntityId,

    And optionally(?)

    • entityId targetEntityId,
    • Vec2F position,
    • int healthLost,
    • string hitType,
    • string damageSourceKind,
    • string targetMaterialKind,
    • bool killed
    { damageType = "IgnoresDef", damage = 1, sourceEntityId = activeItem.ownerEntityId() }
    {healthLost: 1, damageSourceKind: , sourceEntityId: -65536, hitType: Hit, targetMaterialKind: organic, damageDealt: 1, position: {1: 847.35, 2: 903.7}, targetEntityId: -65536}


    Probably be the same as damageRequest?


    Collision Kind is a case-insensitive string used by the world table's collision check functions. A "CollisionSet" is an array of collisionKinds. For materials, they're defined in their .material file. For metamaterials, they're defined in the /assets/metamaterials.config file.

    • Null: For non-loaded areas and some specific metamaterials in vanilla
    • None: No collisions
    • Block: For block materials
    • Platform: For platform materials
    • Dynamic: For eg. the light platforms in the Ancient areas, and doors(?)
    • Slippery: Vanilla uses it so that the Spike Sphere doesn't attach to materials


    JSON object usually put in an array called forceRegions. Vanilla currently only uses it for the kluex boss and the guardianminions.

          "right" : {
            "type" : "RadialForceRegion",
            "outerRadius" : 4,
            "innerRadius" : 0.5,
            "baseTargetRadialVelocity" : -5,
            "controlForce" : 100,
            "categoryWhitelist" : [ "guardianminion" ]


    A list of pathfind nodes


    Lua UserData value which can be used for pathfinding over multiple frames. Has the following two methods:

  • explore([`int` nodeLimit]): Explores the path up to the specified node count limit. Returns `true` if the pathfinding is complete and `false` if it is still incomplete. If nodeLimit is unspecified, this will search up to the configured maximum number of nodes, making it equivalent to world.platformerPathStart
  • result()
  • : Returns the completed path.


    JSON object used to define an image

      base = "image.png",
      hover = "image.png",
      pressed = "image.png",
      disabled = "image.png",


    A vehicle or projectile's movement parameters, returned by mcontroller.parameters(). Not to be confused with ActorMovementParameters.


    A monster, npc, player(...)'s base movement parameters, returned by mcontroller.baseParameters(). Not to be confused with MovementParameters.


    a string defining Image Processing Directives.


    A self-explaining string returned by world.entityType() and entity.entityType():

    • player
    • npc
    • monster
    • object
    • vehicle
    • itemDrop
    • projectile
    • creature ? (seems to be used by switches)

    Quick Navigation