osb/doc/lua/world.md
2023-06-20 14:33:09 +10:00

39 KiB

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.


Tuple<Maybe<Vec2F>, 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. If intersecting a side of the poly, also returns the normal of the intersected side as a second return.


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 EntityIds of the item drops created if successful and nil otherwise.


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 successful and nil otherwise.


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 successful and nil otherwise.


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.

float world.surfaceLevel()

Returns the surface layer base height.


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], [EntityId sourceEntity])

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, [EntityId sourceEntity)

Identical to world.damageTiles but applies to tiles in a circular radius around the specified center point.


List<Vec2I> world.radialTileQuery(Vec2F position, float radius, String layerName)

Returns a list of existing tiles within radius of the given position, on the specified tile layer.


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 to true.

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.


Vec2F world.entityMetaBoundBOx(EntityId entityId)

Returns the meta bound box of the entity, if any.


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.


Maybe<List<MaterialId>> world.biomeBlocksAt(Vec2I position)

Returns the list of biome specific blocks that can place in the biome at the specified position.


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.getNpcScriptParameter(EntityId entityId, String parameterName, [Json defaultValue])

Returns the value of the specified NPC's variant script config parameter, or defaultValue or nil if the parameter is not set or the entity is not an NPC.


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 item descriptors and container positions of all items in the specified container, or nil if the entity is not a container.


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 an asynchronous 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.


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.


bool world.isEntityInteractive(EntityId entityId)

Returns true if an entity with the specified id is player interactive and false otherwise.


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.


DungeonId world.setDungeonId(RectI tileArea, DungeonId dungeonId)

Sets the dungeonId of all tiles within the specified area.


Promise<Vec2I> world.enqueuePlacement(List<Json> distributionConfigs, [DungeonId id])

Enqueues a biome distribution config for placement through world generation. The returned promise is fulfilled with the position of the placement, once it has been placed.


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.placeDungeon(String dungeonName, Vec2I position, [DungeonId dungeonId])

Generates the specified dungeon in the world at the specified position. Does not ignore anchoring rules, will fail if the dungeon can't be placed. 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.