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.

*Id

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

RpcPromise

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.

    ItemDescriptor

    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.

    ItemBag

    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]

    polyF

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

    harvestLevel

    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.

    teamType

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

    • friendly: Cannot be harmed by player weapons except indiscriminate weapons (e.g., players, pets, non-hostile NPCs)
    • enemy: Can be harmed by player weapons (e.g., aggressive monsters, hostile NPCs)
    • passive: Can be harmed by player weapons, after which they become aggressive if they survive (e.g., critters, non-aggressive monsters)
    • ghostly: Cannot be harmed by anything, unaffected by terrain hazards
    • assistant: Cannot be harmed, even by indiscriminate weapons, will not be targeted by monsters or hostile NPCs (e.g., Lana and Nura when they fight at the Baron's Keep, kidnapping victims)
    • environment: Harms players but not monsters or NPCs (e.g., traps)
    • indiscriminate: Harms anything (e.g., molotovs)
    • 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

    damageSourceKind

    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

    damageRepeatGroup

    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

    DamageTeam

    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}

    DamageSource

    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"
  },

    damageRequest

    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}

    damageNotification

    Probably be the same as damageRequest?

    Drawable

    JSON object consisting of either an image or line, with added optional modifiers.

    Either:

    • filepath image
    • Vec2F position

    Or:

    • {Vec2F, Vec2F} line
    • float width

    Optional:

    • float rotation
    • Mat3 transformation
    • boolean fullbright
    • boolean centered
    • boolean mirrored
    • Color color

    The image parameter is the absolute path to a .png image from the Starbound root folder (reminder: the root of a mod folder is also at root level). The position determines where in the Starbound world, in world coordinates, to draw the image.

    The line parameter is a JSON array/simple table of two Vec2Fs (also relative to the world coordinate system); in JSON terms, [[x1, y1], [x2, y2]]. width applies only to lines and determines the pixel thickness with which to draw the line.

    rotation determines the angular rotation (degrees or radians? clockwise or anti-clockwise?) to apply to the image.

    transformation applies only to images and is a 3x3 affine transformation matrix, consisting of three rows of three values each: in JSON terms, [[scaleW, skewX, transX], [skewY, scaleH, transY], [0, 0, 1]] -- the identity matrix is [[1,0,0],[0,1,0],[0,0,1]]. The transformation parameter to a Drawable is used only once in vanilla code, generally preferring to use the animator's transformation group functions on the object's animation instead.

    fullbright draws the shape without being affected by the shadow/lighting shaders.

    centered moves an image to the centre of the position rather than drawing its corner from that position, and should usually be set to true.

    mirrored flips the image if true.

    color applies both to images and to lines and is a multiplier of the RGB values of every pixel in the image or of the line segment.

    collisionKinds

    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

    PhysicsForceRegion

    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" ]
      }
    }

    PlatformerAStar::Path

    A list of pathfind nodes

    PlatformerAStar::PathFinder

    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.

    imageSet

    JSON object used to define an image 

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

    MovementParameters

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

    ActorMovementParameters

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

    directives

    a string defining Image Processing Directives.

    entityType

    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

    Retrieved from "https://starbounder.org/mediawiki/index.php?title=Modding:Lua/Starbound_Datatypes&oldid=200543"