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(). 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

    Surprisingly simple, just the liquid ID and its amount.

    • int liquidId
    • int amount


    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.


    First noted usage by widget.itemGridItems(String widgetName). this entry needs filling.

    Vec2F and Vec2I

    JSON object which contains x and y. "I" is for Integer, "F" is for "Float"

    [x = 0, y = 2]

    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 edges. The last coordinates form a line with the first ones.

    [ [-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] ]


    Seems to be the poor man's boolean, where 0 = false and 1 = true?


    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 to blocks
    • plantish: damages to plants
    • beamish: Used by the pickslash weaponability
    • explosive: Used by the meteor explosions
    • fire:
    • tilling:
    • damage:
    • knockback: used by shields
    • Environment:
    • IgnoresDef: Ignores the target's protection stat.
    • NoDamage:


    Seems to be an arbitrary string, unsure how it is used exactly. Might be to define which sound to play? Vanilla ones:

    applystatus, axe, bite, broadsword, bugnet, dagger, default, electric, electricbroadsword, electricfist, electrichammer, electricplasma, falling, fire, firebroadsword, firehammer, fireplasma, fist, fiststrong, foldingchair, fryingpan, gnomebeam, hammer, hidden, ice, icehammer, iceplasma, nodamage, plasma, poison, poisondagger, poisonhammer, poisonlash, poisonplasma, sawblade, shield, shortsword, slash, spear, standardbullet


    Seems to be an arbitrary string, unsure how it is used exactly.

    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,
    • int damage,
    • string teamType,
    • string damageType,
    • string damageSourceKind,
    • 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