Modding:Lua/Tables/World
The world table contains functions that perform actions within a specified such as querying or modifying entities, tiles, etc. in that world.
String
world.type()
Returns a string describing the world's type. For terrestrial worlds this will be the primary biome, for instance worlds this will be the instance name, and for ship or generic worlds this will be 'unknown'.
bool
world.terrestrial()
Returns a true
if the current world is a terrestrial world, i.e. a planet, and false
otherwise.
Vec2I
world.size()
Returns a vector describing the size of the current world.
float
world.magnitude(Vec2F
position1, Vec2F
position2)
Returns the magnitude of the distance between the specified world positions. Use this rather than simple vector subtraction to handle world wrapping.
Vec2F
world.distance(Vec2F
position1, Vec2F
position2)
Returns the vector difference between the specified world positions. Use this rather than simple vector subtraction to handle world wrapping.
bool
world.polyContains(PolyF
poly, Vec2F
position)
Returns true
if the specified poly contains the specified position in world space and false
otherwise.
Vec2F
world.xwrap(Vec2F
position)
Returns the specified position with its X coordinate wrapped around the world width.
float
world.xwrap(float
xPosition)
Returns the specified X position wrapped around the world width.
Variant<Vec2F, float>
world.nearestTo(Variant<Vec2F, float>
sourcePosition, Variant<Vec2F, float>
targetPosition)
Returns the point nearest to (i.e. on the same side of the world as) the source point. Either argument can be specified as a Vec2F
point or as a float
X position. The type of the targetPosition determines the return type.
bool
world.pointCollision(Vec2F
point, [CollisionSet
collisionKinds])
Returns true
if the generated collision geometry at the specified point matches any of the specified collision kinds and false
otherwise.
bool
world.pointTileCollision(Vec2F
point, [CollisionSet
collisionKinds])
Returns true
if the tile at the specified point matches any of the specified collision kinds and false
otherwise.
Maybe<Vec2F>
world.lineCollision(Vec2F
startPoint, Vec2F
endPoint, [CollisionSet
collisionKinds])
If the line between the specified points overlaps any generated collision geometry of the specified collision kinds, returns the point at which the line collides, or nil
if the line does not collide.
bool
world.lineTileCollision(Vec2F
startPoint, Vec2F
endPoint, [CollisionSet
collisionKinds])
Returns true
if the line between the specified points overlaps any tiles of the specified collision kinds and false
otherwise.
Maybe<pair<Vec2F, Vec2F>>
world.lineTileCollisionPoint(Vec2F
startPoint, Vec2F
endPoint, [CollisionSet
collisionKinds])
Returns a table of {`position`, `normal`} where `position` is the position that the line intersects the first collidable tile, and `normal` is the collision normal. Returns nil
if no tile is intersected.
bool
world.rectCollision(RectF
rect, [CollisionSet
collisionKinds])
Returns true
if the specified rectangle overlaps any generated collision geometry of the specified collision kinds and false
otherwise.
bool
world.rectTileCollision(RectF
rect, [CollisionSet
collisionKinds])
Returns true
if the specified rectangle overlaps any tiles of the specified collision kinds and false
otherwise.
bool
world.polyCollision(PolyF
poly, [Vec2F
position], [CollisionSet
collisionKinds])
Returns true
if the specified polygon overlaps any generated collision geometry of the specified collision kinds and false
otherwise. If a position is specified, the polygon coordinates will be treated as relative to that world position.
List<Vec2I>
world.collisionBlocksAlongLine(Vec2F
startPoint, Vec2F
endPoint, [CollisionSet
collisionKinds], [int
maxReturnCount])
Returns an ordered list of tile positions along the line between the specified points that match any of the specified collision kinds. If maxReturnCount is specified, the function will only return up to that number of points.
List<pair<Vec2I, LiquidLevel>>
world.liquidAlongLine(Vec2F
startPoint, Vec2F
endPoint)
Returns a list of pairs containing a position and a LiquidLevel
for all tiles along the line between the specified points that contain any liquid.
Vec2F
world.resolvePolyCollision(PolyF
poly, Vec2F
position, float
maximumCorrection, [CollisionSet
collisionKinds])
Attempts to move the specified poly (relative to the specified position) such that it does not collide with any of the specified collision kinds. Will only move the poly up to the distance specified by maximumCorrection. Returns nil
if the collision resolution fails.
bool
world.tileIsOccupied(Vec2I
tilePosition, [bool
foregroundLayer], [bool
includeEphemeral])
Returns true
if the specified tile position is occupied by a material or tile entity and false
if it is empty. The check will be performed on the foreground tile layer if foregroundLayer is true
(or unspecified) and the background tile layer if it is false
. The check will include ephemeral tile entities such as preview objects if includeEphemeral is true
, and will not include these entities if it is false
(or unspecified).
bool
world.placeObject(String
objectName, Vec2I
tilePosition, [int
direction], [Json
parameters])
Attempts to place the specified object into the world at the specified position, preferring it to be right-facing if direction is positive (or unspecified) and left-facing if it is negative. If parameters are specified they will be applied to the object. Returns true
if the object is placed successfully and false
otherwise.
EntityId
world.spawnItem(ItemDescriptor
item, Vec2F
position, [unsigned
count], [Json
parameters], [Vec2F
velocity], [float
intangibleTime])
Attempts to spawn the specified item into the world as the specified position. If item is specified as a name, it will optionally apply the specified count and parameters. The item drop entity can also be spawned with an initial velocity and intangible time (delay before it can be picked up) if specified. Returns an EntityId
of the item drop if successful and nil
otherwise.
List<EntityId>
world.spawnTreasure(Vec2F
position, String
poolName, float
level, [unsigned
seed])
Attempts to spawn all items in an instance of the specified treasure pool with the specified level and seed at the specified world position. Returns a list of EntityId
s of the item drops created if successful and nil
otherwise.
Note that instead of a list of EntityId
that the documentation says this function produces on success, it actually produces a list of (numeric) zeros, equal in size to the number of items spawned, on success. To find the items spawned, you must use world.itemDropQuery with an appropriate query region, with the caveat that the query will return all items in the region, even if they did not come from this spawn. Furthermore, this function returns an empty list, not a nil, on failure, making failure programmatically indistinguishable from a successful spawn that generated no items. On failure, a warning message is written into the Starbound log.
EntityId
world.spawnMonster(String
monsterType, Vec2F
position, [Json
parameters])
Attempts to spawn a monster of the specified type at the specified position. If parameters are specified they will be applied to the spawned monster. If they are unspecified, they default to an object setting aggressive to be randomly true
or false
. Level for the monster may be specified in parameters. Returns the EntityId
of the spawned monster if it is run from a server-side entity and is successful, or nil
.
EntityId
world.spawnNpc(Vec2F
position, String
species, String
npcType, float
level, [unsigned
seed], [Json
parameters])
Attempts to spawn an NPC of the specified type, species, level with the specified seed and parameters at the specified position. Returns EntityId
of the spawned NPC if successful and nil
otherwise.
EntityId
world.spawnStagehand(Vec2F
position, String
type, [Json
overrides])
Attempts to spawn a stagehand of the specified type at the specified position with the specified override parameters. Returns EntityId
of the spawned stagehand if it is run from a server-side entity and is successful, or nil
.
EntityId
world.spawnProjectile(String
projectileName, Vec2F
position, [EntityId
sourceEntityId], [Vec2F
direction], [bool
trackSourceEntity], [Json
parameters])
Attempts to spawn a projectile of the specified type at the specified position with the specified source entity id, direction, and parameters. If trackSourceEntity is true
then the projectile's position will be locked relative to its source entity's position. Returns the EntityId
of the spawned projectile if successful and nil
otherwise.
EntityId
world.spawnVehicle(String
vehicleName, Vec2F
position, [Json
overrides])
Attempts to spawn a vehicle of the specified type at the specified position with the specified override parameters. Returns the EntityId
of the spawned vehicle if successful and nil
otherwise.
float
world.threatLevel()
Returns the threat level of the current world.
double
world.time()
Returns the absolute time of the current world.
unsigned
world.day()
Returns the absolute numerical day of the current world.
double
world.timeOfDay()
Returns a value between 0 and 1 indicating the time within the day of the current world.
float
world.dayLength()
Returns the duration of a day on the current world.
Json
world.getProperty(String
propertyName, [Json
defaultValue])
Returns the JSON value of the specified world property, or defaultValue or nil
if it is not set.
void
world.setProperty(String
propertyName, Json
value)
Sets the specified world property to the specified value.
LiquidLevel
world.liquidAt(Vec2I
position)
Returns the LiquidLevel
at the specified tile position, or nil
if there is no liquid.
LiquidLevel
world.liquidAt(RectF
region)
Returns the average LiquidLevel
of the most plentiful liquid within the specified region, or nil
if there is no liquid.
float
world.gravity(Vec2F
position)
Returns the gravity at the specified position. This should be consistent for all non-dungeon tiles in a world but can be altered by dungeons.
bool
world.spawnLiquid(Vec2F
position, LiquidId
liquid, float
quantity)
Attempts to place the specified quantity of the specified liquid at the specified position. Returns true
if successful and false
otherwise.
LiquidLevel
world.destroyLiquid(Vec2F
position)
Removes any liquid at the specified position and returns the LiquidLevel containing the type and quantity of liquid removed, or nil
if no liquid is removed.
bool
world.isTileProtected(Vec2F
position)
Returns true
if the tile at the specified position is protected and false
otherwise.
PlatformerAStar::Path
world.findPlatformerPath(Vec2F
startPosition, Vec2F
endPosition, ActorMovementParameters
movementParameters, `PlatformerAStar::Parameters` searchParameters)
Attempts to synchronously pathfind between the specified positions using the specified movement and pathfinding parameters. Returns the path as a list of nodes as successful, or nil
if no path is found.
PlatformerAStar::PathFinder
world.platformerPathStart(Vec2F
startPosition, Vec2F
endPosition, ActorMovementParameters
movementParameters, PlatformerAStar::Parameters
searchParameters)
Creates and returns a Lua UserData value which can be used for pathfinding over multiple frames. The `PathFinder` returned has the following two methods:
bool
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.
PlatformerAStar::Path
result()
Returns the completed path.
float
world.lightLevel(Vec2F
position)
Returns the current logical light level at the specified position. Requires recalculation of lighting, so this should be used sparingly.
float
world.windLevel(Vec2F
position)
Returns the current wind level at the specified position.
bool
world.breathable(Vec2F
position)
Returns true
if the world is breathable at the specified position and false
otherwise.
List<String>
world.environmentStatusEffects(Vec2F
position)
Returns a list of the environmental status effects at the specified position.
bool
world.underground(Vec2F
position)
Returns true
if the specified position is below the world's surface level and false
otherwise.
bool
world.inSurfaceLayer(Vec2I
position)
Returns true
if the world is terrestrial and the specified position is within its surface layer, and false
otherwise.
int
world.oceanLevel(Vec2I
position)
If the specified position is within a region that has ocean (endless) liquid, returns the world Y level of that ocean's surface, or 0 if there is no ocean in the specified region.
Variant<String, bool>
world.material(Vec2F
position, String
layerName)
Returns the name of the material at the specified position and layer. Layer can be specified as 'foreground' or 'background'. Returns false
if the space is empty in that layer. Returns nil
if the material is NullMaterial (e.g. if the position is in an unloaded sector).
String
world.mod(Vec2F
position, String
layerName)
Returns the name of the mod at the specified position and layer, or nil
if there is no mod.
float
world.materialHueShift(Vec2F
position, String
layerName)
Returns the hue shift of the material at the specified position and layer.
float
world.modHueShift(Vec2F
position, String
layerName)
Returns the hue shift of the mod at the specified position and layer.
unsigned
world.materialColor(Vec2F
position, String
layerName)
Returns the color variant (painted color) of the material at the specified position and layer.
void
world.setMaterialColor(Vec2F
position, String
layerName, unsigned
color)
Sets the color variant of the material at the specified position and layer to the specified color.
bool
world.damageTiles(List<Vec2I>
positions, String
layerName, Vec2F
sourcePosition, String
damageType, float
damageAmount, [unsigned
harvestLevel])
Damages all tiles in the specified layer and positions by the specified amount. The source position of the damage determines the initial direction of the damage particles. Damage types are: "plantish", "blockish", "beamish", "explosive", "fire", "tilling". Harvest level determines whether destroyed materials or mods will drop as items. Returns true
if any damage was done and false
otherwise.
bool
world.damageTileArea(Vec2F
center, float
radius, String
layerName, Vec2F
sourcePosition, String
damageType, float
damageAmount, [unsigned
harvestLevel)
Identical to world.damageTiles but applies to tiles in a circular radius around the specified center point.
bool
world.placeMaterial(Vec2I
position, String
layerName, String
materialName, [int
hueShift], [bool
allowOverlap])
Attempts to place the specified material in the specified position and layer. If allowOverlap is true
the material can be placed in a space occupied by mobile entities, otherwise such placement attempts will fail. Returns true
if the placement succeeds and false
otherwise.
bool
world.placeMod(Vec2I
position, String
layerName, String
modName, [int
hueShift], [bool
allowOverlap])
Attempts to place the specified mod in the specified position and layer. If allowOverlap is true
the mod can be placed in a space occupied by mobile entities, otherwise such placement attempts will fail. Returns true
if the placement succeeds and false
otherwise.
List<EntityId>
world.entityQuery(Vec2F
position, Variant<Vec2F, float>
positionOrRadius, [Json
options])
Queries for entities in a specified area of the world and returns a list of their entity ids. Area can be specified either as the Vec2F
lower left and upper right positions of a rectangle, or as the Vec2F
center and float
radius of a circular area. The following additional parameters can be specified in options:
- __withoutEntityId__ - Specifies an
EntityId
that will be excluded from the returned results - __includedTypes__ - Specifies a list of one or more
String
entity types that the query will return. In addition to standard entity type names, this list can include "mobile" for all mobile entity types or "creature" for players, monsters and NPCs. - __boundMode__ - Specifies the bounding mode for determining whether entities fall within the query area. Valid options are "position", "collisionarea", "metaboundbox". Defaults to "collisionarea" if unspecified.
- __order__ - A
String
used to specify how the results will be ordered. If this is set to "nearest" the entities will be sorted by ascending distance from the first positional argument. If this is set to "random" the list of results will be shuffled. - __callScript__ - Specifies a
String
name of a function that should be called in the script context of all scripted entities matching the query. - __callScriptArgs__ - Specifies a list of arguments that will be passed to the function called by callScript.
- __callScriptResult__ - Specifies a
LuaValue
that the function called by callScript must return; entities whose script calls do not return this value will be excluded from the results. Defaults totrue
.
List<EntityId>
world.monsterQuery(Vec2F
position, Variant<Vec2F, float>
positionOrRadius, [Json
options])
Identical to world.entityQuery but only considers monsters.
List<EntityId>
world.npcQuery(Vec2F
position, Variant<Vec2F, float>
positionOrRadius, [Json
options])
Identical to world.entityQuery but only considers NPCs.
List<EntityId>
world.objectQuery(Vec2F
position, Variant<Vec2F, float>
positionOrRadius, [Json
options])
Similar to world.entityQuery but only considers objects. Allows an additional option, __name__, which specifies a String
object type name and will only return objects of that type.
List<EntityId>
world.itemDropQuery(Vec2F
position, Variant<Vec2F, float>
positionOrRadius, [Json
options])
Identical to world.entityQuery but only considers item drops.
List<EntityId>
world.playerQuery(Vec2F
position, Variant<Vec2F, float>
positionOrRadius, [Json
options])
Identical to world.entityQuery but only considers players.
List<EntityId>
world.loungeableQuery(Vec2F
position, Variant<Vec2F, float>
positionOrRadius, [Json
options])
Similar to world.entityQuery but only considers loungeable entities. Allows an additional option, __orientation__, which specifies the String
name of a loungeable orientation ("sit", "lay" or "stand") and only returns loungeable entities which use that orientation.
List<EntityId>
world.entityLineQuery(Vec2F
startPosition, Vec2F
endPosition, [Json
options])
Similar to world.entityQuery but only returns entities that intersect the line between the specified positions.
List<EntityId>
world.objectLineQuery(Vec2F
startPosition, Vec2F
endPosition, [Json
options])
Identical to world.entityLineQuery but only considers objects.
List<EntityId>
world.npcLineQuery(Vec2F
startPosition, Vec2F
endPosition, [Json
options])
Identical to world.entityLineQuery but only considers NPCs.
EntityId
world.objectAt(Vec2I
tilePosition)
Returns the entity id of any object occupying the specified tile position, or nil
if the position is not occupied by an object.
bool
world.entityExists(EntityId
entityId)
Returns true
if an entity with the specified id exists in the world and false
otherwise.
DamageTeam
world.entityDamageTeam(EntityId
entityId)
Returns the current damage team (team type and team number) of the specified entity, or nil
if the entity doesn't exist.
bool
world.entityCanDamage(EntityId
sourceId, EntityId
targetId)
Returns true
if the specified source entity can damage the specified target entity using their current damage teams and false
otherwise.
bool
world.entityAggressive(EntityId
entity)
Returns true
if the specified entity is an aggressive monster or NPC and false
otherwise.
String
world.entityType(EntityId
entityId)
Returns the entity type name of the specified entity, or nil
if the entity doesn't exist.
Vec2F
world.entityPosition(EntityId
entityId)
Returns the current world position of the specified entity, or nil
if the entity doesn't exist.
Vec2F
world.entityMouthPosition(EntityId
entityId)
Returns the current world mouth position of the specified player, monster, NPC or object, or nil
if the entity doesn't exist or isn't a valid type.
Vec2F
world.entityVelocity(EntityId
entityId)
Returns the current velocity of the entity if it is a vehicle, monster, NPC or player and nil
otherwise.
unsigned
world.entityCurrency(EntityId
entityId, String
currencyType)
Returns the specified player entity's stock of the specified currency type, or nil
if the entity is not a player.
unsigned
world.entityHasCountOfItem(EntityId
entityId, Json
itemDescriptor, [bool
exactMatch])
Returns the nubmer of the specified item that the specified player entity is currently carrying, or nil
if the entity is not a player. If exactMatch is true
then parameters as well as item name must match.
NOTE: This function currently does not work correctly over the network, making it inaccurate when not used from client side scripts such as status.
Vec2F
world.entityHealth(EntityId
entityId)
Returns a Vec2F
containing the specified entity's current and maximum health if the entity is a player, monster or NPC and nil
otherwise.
String
world.entitySpecies(EntityId
entityId)
Returns the name of the specified entity's species if it is a player or NPC and nil
otherwise.
String
world.entityGender(EntityId
entityId)
Returns the name of the specified entity's gender if it is a player or NPC and nil
otherwise.
String
world.entityName(EntityId
entityId)
Returns a String
name of the specified entity which has different behavior for different entity types. For players, monsters and NPCs, this will be the configured name of the specific entity. For objects or vehicles, this will be the name of the object or vehicle type. For item drops, this will be the name of the contained item.
String
world.entityTypeName(EntityId
entityId)
Similar to world.entityName but returns the names of configured types for NPCs and monsters.
String
world.entityDescription(EntityId
entityId, [String
species])
Returns the configured description for the specified inspectable entity (currently only objects and plants support this). Will return a species-specific description if species is specified and a generic description otherwise.
JsonArray
world.entityPortrait(EntityId
entityId, String
portraitMode)
Generates a portrait of the specified entity in the specified portrait mode and returns a list of drawables, or nil
if the entity is not a portrait entity.
String
world.entityHandItem(EntityId
entityId, String
handName)
Returns the name of the item held in the specified hand of the specified player or NPC, or nil
if the entity is not holding an item or is not a player or NPC. Hand name should be specified as "primary" or "alt".
ItemDescriptor
world.entityHandItemDescriptor(EntityId
entityId, String
handName)
Similar to world.entityHandItem but returns the full descriptor of the item rather than the name.
ItemDescriptor
world.itemDropItem(EntityId
entityId)
Returns the item descriptor of an item drop's contents.
String
world.entityUniqueId(EntityId
entityId)
Returns the unique id of the specified entity, or nil
if the entity does not have a unique id.
Json
world.getObjectParameter(EntityId
entityId, String
parameterName, [Json
defaultValue])
Returns the value of the specified object's config parameter, or defaultValue or nil
if the parameter is not set or the entity is not an object.
List<Vec2I>
world.objectSpaces(EntityId
entityId)
Returns a list of tile positions that the specified object occupies, or nil
if the entity is not an object.
int
world.farmableStage(EntityId
entityId)
Returns the current growth stage of the specified farmable object, or nil
if the entity is not a farmable object.
int
world.containerSize(EntityId
entityId)
Returns the total capacity of the specified container, or nil
if the entity is not a container.
bool
world.containerClose(EntityId
entityId)
Visually closes the specified container. Returns true
if the entity is a container and false
otherwise.
bool
world.containerOpen(EntityId
entityId)
Visually opens the specified container. Returns true
if the entity is a container and false
otherwise.
JsonArray
world.containerItems(EntityId
entityId)
Returns a list of pairs of position (k) and item descriptor (v) for all items in the specified container, or nil
if the entity is not a container. Positions start from 1, as opposed to starting from 0 like any offset-based functions below.
ItemDescriptor
world.containerItemAt(EntityId
entityId, unsigned
offset)
Returns an item descriptor of the item at the specified position in the specified container, or nil
if the entity is not a container or the offset is out of range.
bool
world.containerConsume(EntityId
entityId, ItemDescriptor
item)
Attempts to consume items from the specified container that match the specified item descriptor and returns true
if successful, false
if unsuccessful, or nil
if the entity is not a container. Only succeeds if the full count of the specified item can be consumed.
bool
world.containerConsumeAt(EntityId
entityId, unsigned
offset, unsigned
count)
Similar to world.containerConsume but only considers the specified slot within the container.
unsigned
world.containerAvailable(EntityId
entityId, ItemDescriptor
item)
Returns the number of the specified item that are currently available to consume in the specified container, or nil
if the entity is not a container.
JsonArray
world.containerTakeAll(EntityId
entityId)
Similar to world.containerItems but consumes all items in the container.
ItemDescriptor
world.containerTakeAt(EntityId
entityId, unsigned
offset)
Similar to world.containerItemAt, but consumes all items in the specified slot of the container.
ItemDescriptor
world.containerTakeNumItemsAt(EntityId
entityId, unsigned
offset, unsigned
count)
Similar to world.containerTakeAt, but consumes up to (but not necessarily equal to) the specified count of items from the specified slot of the container and returns only the items consumed.
unsigned
world.containerItemsCanFit(EntityId
entityId, ItemDescriptor
item)
Returns the number of times the specified item can fit in the specified container, or nil
if the entity is not a container.
Json
world.containerItemsFitWhere(EntityId
entityId, ItemDescriptor
items)
Returns a JsonObject containing a list of "slots" the specified item would fit and the count of "leftover" items that would remain after attempting to add the items. Returns nil
if the entity is not a container.
ItemDescriptor
world.containerAddItems(EntityId
entityId, ItemDescriptor
items)
Adds the specified items to the specified container. Returns the leftover items after filling the container, or all items if the entity is not a container.
ItemDescriptor
world.containerStackItems(EntityId
entityId, ItemDescriptor
items)
Similar to world.containerAddItems but will only combine items with existing stacks and will not fill empty slots.
ItemDescriptor
world.containerPutItemsAt(EntityId
entityId, ItemDescriptor
items, unsigned
offset)
Similar to world.containerAddItems but only considers the specified slot in the container.
ItemDescriptor
world.containerItemApply(EntityId
entityId, ItemDescriptor
items, unsigned
offset)
Attempts to combine the specified items with the current contents (if any) of the specified container slot and returns any items unable to be placed into the slot.
ItemDescriptor
world.containerSwapItemsNoCombine(EntityId
entityId, ItemDescriptor
items, unsigned
offset)
Places the specified items into the specified container slot and returns the previous contents of the slot if successful, or the original items if unsuccessful.
ItemDescriptor
world.containerSwapItems(EntityId
entityId, ItemDescriptor
items, unsigned
offset)
A combination of world.containerItemApply and world.containerSwapItemsNoCombine that attempts to combine items before swapping and returns the leftovers if stacking was successful or the previous contents of the container slot if the items did not stack.
LuaValue
world.callScriptedEntity(EntityId
entityId, String
functionName, [LuaValue
args ...])
Attempts to call the specified function name in the context of the specified scripted entity with the specified arguments and returns the result. This method is synchronous and thus can only be used on local master entities, i.e. scripts run on the server may only call scripted entities that are also server-side master and scripts run on the client may only call scripted entities that are client-side master on that client. For more featureful entity messaging, use world.sendEntityMessage.
RpcPromise<Json>
world.sendEntityMessage(Variant<EntityId, String>
entityId, String
messageType, [LuaValue
args ...])
Sends a message to an entity with the specified entity id or unique id with the specified message type and arguments and returns an RpcPromise
which can be used to receive the result of the message when available. See the message table for information on entity message handling. This function should not be called in any entity's init function as the sending entity will not have been fully loaded.
When called on a remote entity, it is asynchronous. On local entities it is synchronous.
Sending messages to nonexistent entities runs the risk of hard crashes (of the segmentation fault variety), so it's a good idea to make sure the entity does indeed exist:
if world.entityExists(entityId) then world.sendEntityMessage(entityId, "someMessage") end
RpcPromise<Vec2F>
world.findUniqueEntity(String
uniqueId)
Attempts to find an entity on the server by unique id and returns an `RpcPromise` that can be used to get the position of that entity if successful.
bool
world.loungeableOccupied(EntityId
entityId)
Checks whether the specified loungeable entity is currently occupied and returns true
if it is occupied, false
if it is unoccupied, or nil
if it is not a loungeable entity.
bool
world.isMonster(EntityId
entityId, [bool
aggressive])
Returns true
if the specified entity exists and is a monster and false
otherwise. If aggressive is specified, will return false
unless the monster's aggressive state matches the specified value.
String
world.monsterType(EntityId
entityId)
Returns the monster type of the specified monster, or nil
if the entity is not a monster.
bool
world.isNpc(EntityId
entityId, [int
damageTeam])
Returns true
if the specified entity exists and is an NPC and false
otherwise. If damageTeam is specified, will return false
unless the NPC's damage team number matches the specified value.
String
world.npcType(EntityId
entityId)
Returns the NPC type of the specified NPC, or nil
if the entity is not an NPC.
String
world.stagehandType(EntityId
entityId)
Returns the stagehand type of the specified stagehand, or nil
if the entity is not a stagehand.
void
world.debugPoint(Vec2F
position, Color
color)
Displays a point visible in debug mode at the specified world position.
void
world.debugLine(Vec2F
startPosition, Vec2F
endPosition, Color
color)
Displayes a line visible in debug mode between the specified world positions.
void
world.debugPoly(PolyF
poly, Color
color)
Displays a polygon consisting of the specified points that is visible in debug mode.
void
world.debugText(String
formatString, [LuaValue
formatValues ...], Vec2F
position, Color
color)
Displays text visible in debug mode at the specified position using the specified format string and optional formatted values.
The following additional world bindings are available only for scripts running on the server.
bool
world.breakObject(EntityId
entityId, bool
smash)
Breaks the specified object and returns true
if successful and false
otherwise. If smash is true
the object will not (by default) drop any items.
bool
world.isVisibleToPlayer(RectF
region)
Returns true
if any part of the specified region overlaps any player's screen area and false
otherwise.
bool
world.loadRegion(RectF
region)
Attempts to load all sectors overlapping the specified region and returns true
if all sectors are fully loaded and false
otherwise.
bool
world.regionActive(RectF
region)
Returns true
if all sectors overlapping the specified region are fully loaded and false
otherwise.
void
world.setTileProtection(DungeonId
dungeonId, bool
protected)
Enables or disables tile protection for the specified dungeon id.
DungeonId
world.dungeonId(Vec2F
position)
Returns the dungeon id at the specified world position.
bool
world.isPlayerModified(RectI
region)
Returns true
if any tile within the specified region has been modified (placed or broken) by a player and false
otherwise.
LiquidLevel
world.forceDestroyLiquid(Vec2F
position)
Identical to world.destroyLiquid but ignores tile protection.
EntityId
world.loadUniqueEntity(String
uniqueId)
Forces (synchronous) loading of the specified unique entity and returns its non-unique entity id or 0 if no such unique entity exists.
void
world.setUniqueId(EntityId
entityId, [String
uniqueId])
Sets the unique id of the specified entity to the specified unique id or clears it if no unique id is specified.
ItemDescriptor
world.takeItemDrop(EntityId
targetEntityId, [EntityId
sourceEntityId])
Takes the specified item drop and returns an ItemDescriptor
of its contents or nil
if the operation fails. If a source entity id is specified, the item drop will briefly animate toward that entity.
void
world.setPlayerStart(Vec2F
position, [bool
respawnInWorld])
Sets the world's default beam-down point to the specified position. If respawnInWorld is set to true
then players who die in that world will respawn at the specified start position rather than being returned to their ships.
List<EntityId>
world.players()
Returns a list of the entity ids of all players currently in the world.
String
world.fidelity()
Returns the name of the fidelity level at which the world is currently running. See worldserver.config for fidelity configuration.
String
world.flyingType()
Returns the current flight status of a ship world.
String
world.warpPhase()
Returns the current warp phase of a ship world.
void
world.setUniverseFlag(String
flagName)
Sets the specified universe flag on the current universe.
List<String>
world.universeFlags()
Returns a list of all universe flags set on the current universe.
bool
world.universeFlagSet(String
flagName)
Returns true
if the specified universe flag is set and false
otherwise.
double
world.skyTime()
Returns the current time for the world's sky.
void
world.setSkyTime(double
time)
Sets the current time for the world's sky to the specified value.
void
world.placeDungeon(String
dungeonName, Vec2I
position, [DungeonId
dungeonId])
Generates the specified dungeon in the world at the specified position, ignoring normal dungeon anchoring rules. If a dungeon id is specified, it will be assigned to the dungeon.
void
world.addBiomeRegion(Vec2I
position, String
biomeName, String
subBlockSelector, int
width)
Adds a biome region to the world, centered on `position`, `width` blocks wide.
void
world.expandBiomeRegion(Vec2I
position, int
width)
Expands the biome region currently at `position` by `width` blocks.
void
world.pregenerateAddBiome(Vec2I
position, int
width)
Signals a region for asynchronous generation. The region signaled is the region that needs to be generated to add a biome region of `width` tiles to `position`.
void
world.pregenerateExpandBiome(Vec2I
position, int
width)
Signals a region for asynchronous generation. The region signaled is the region that needs to be generated to expand the biome at `position` by `width` blocks.
void
world.setLayerEnvironmentBiome(Vec2I
position)
Sets the environment biome for a layer to the biome at `position`.
void
world.setPlanetType(String
planetType, String
, primaryBiomeName)
Sets the planet type of the current world to `planetType` with primary biome `primaryBiomeName`.
void
world.setDungeonGravity(DungeonId
dungeonId, Maybe<float>
gravity)
Sets the overriding gravity for the specified dungeon id, or returns it to the world default if unspecified.
void
world.setDungeonBreathable(DungeonId
dungeonId, Maybe<bool>
breathable)
Sets the overriding breathability for the specified dungeon id, or returns it to the world default if unspecified.
Portal - Basics - JSON - Lua - Assets - Guides
Tables - Hooks - Tips & Tricks - Libraries - All Pages