Modding:Lua/Starbound Datatypes
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 functionRpcPromiseVariable: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
liquidIdfloat
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
nameint
countJSON
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 hazardsassistant
: 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 blocksplantish
: damages plantsbeamish
: Used by the pickslash weaponabilityexplosive
: Used by the meteor explosionsfire
: Damages plants and wooden blockstilling
:damage
: Basic damage to everythingknockback
: Used by shieldsEnvironment
:IgnoresDef
: Ignores the target's protection statNoDamage
: 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
typeint
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 orList<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
imageVec2F
position
Or:
{Vec2F, Vec2F}
linefloat
width
Optional:
float
rotationMat3
transformationboolean
fullbrightboolean
centeredboolean
mirroredColor
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 vanillaNone
: No collisionsBlock
: For block materialsPlatform
: For platform materialsDynamic
: 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.platformerPathStartresult()
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)