starbound documentation - media.readthedocs.org · what is starbound 3. 2 actor mcontroller rectf...

Starbound DocumentationRelease 1.0

Starbound

Jul 18, 2017

Contents

1 What is starbound 3

2 Documentation 52.1 actor mcontroller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.1.1 RectF mcontroller.boundBox() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.1.2 PolyF mcontroller.collisionPoly() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.1.3 PolyF mcontroller.collisionBody() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.1.4 Vec2F mcontroller.position() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.1.5 float mcontroller.xPosition() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.1.6 float mcontroller.yPosition() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.1.7 Vec2F mcontroller.velocity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.1.8 float mcontroller.xVelocity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.1.9 float mcontroller.yVelocity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.1.10 float mcontroller.rotation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.1.11 bool mcontroller.isColliding() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.1.12 bool mcontroller.isNullColliding() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.1.13 bool mcontroller.isCollisionStuck() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.1.14 float mcontroller.stickingDirection() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.1.15 float mcontroller.liquidPercentage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.1.16 LiquidId mcontroller.liquidId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.1.17 bool mcontroller.onGround() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.1.18 void mcontroller.setPosition(Vec2F position) . . . . . . . . . . . . . . . . . . . . . . . . 82.1.19 void mcontroller.setXPosition(float x) . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.1.20 void mcontroller.setYPosition(float y) . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.1.21 void mcontroller.translate(Vec2F direction) . . . . . . . . . . . . . . . . . . . . . . . . . 82.1.22 void mcontroller.setVelocity(Vec2F velocity) . . . . . . . . . . . . . . . . . . . . . . . . 82.1.23 void mcontroller.setXVelocity(Vec2F xVelocity) . . . . . . . . . . . . . . . . . . . . . . 92.1.24 void mcontroller.setYVelocity(Vec2F yVelocity) . . . . . . . . . . . . . . . . . . . . . . 92.1.25 void mcontroller.addMomentum(Vec2F momentum) . . . . . . . . . . . . . . . . . . . . 92.1.26 void mcontroller.setRotation(float angle) . . . . . . . . . . . . . . . . . . . . . . . . . 92.1.27 void mcontroller.controlApproachVelocityAlongAngle(float angle, float targetVeloc-

ity, float maxControlForce, bool positiveOnly = false) . . . . . . . . . . . . . . . . . . 112.1.28 void mcontroller.controlApproachXVelocity(float targetVelocity, float maxControl-

Force) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.1.29 void mcontroller.controlApproachYVelocity(float targetVelocity, float maxControl-

Force) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

i

2.2 animator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.2.1 bool animator.setAnimationState(String stateType, String State, bool startNew = false) 132.2.2 String animator.animationState(String stateType) . . . . . . . . . . . . . . . . . . . . 142.2.3 Json animator.animationStateProperty(String stateType, String propertyName) . . . . 142.2.4 void animator.setGlobalTag(String tagName, String tagValue) . . . . . . . . . . . . 142.2.5 void animator.setPartTag(String partType, String tagName, String tagValue) . . . 142.2.6 void animator.setAnimationRate(float rate) . . . . . . . . . . . . . . . . . . . . . . . . 142.2.7 void animator.rotateGroup(String rotationGroup, float targetAngle, bool immediate) 142.2.8 float animator.currentRotationAngle(String rotationGroup) . . . . . . . . . . . . . . . 142.2.9 bool animator.hasTransformationGroup(String transformationGroup) . . . . . . . . . . 142.2.10 void animator.translateTransformationGroup(String transformationGroup, Vec2F

translate) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.2.11 void animator.rotateTransformationGroup(String transformationGroup, float rotation) 152.2.12 void animator.scaleTransformationGroup(String transformationGroup, float scale,

[Vec2F scaleCenter]) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.2.13 void animator.transformTransformationGroup(String transformationGroup, float a,

float b, float c, float d, float tx, float ty) . . . . . . . . . . . . . . . . . . . . . 152.2.14 void animator.resetTransformationGroup(String transformationGroup) . . . . . . . . . 152.2.15 void animator.setParticleEmitterActive(String emitterName, bool active) . . . . . . . 152.2.16 void animator.setParticleEmitterEmissionRate(String emitterName, float emissionRate) 152.2.17 void animator.setParticleEmitterBurstCount(String emitterName, unsigned burstCount) 162.2.18 void animator.setParticleEmitterOffsetRegion(String emitterName, RectF offsetRegion) 162.2.19 void animator.burstParticleEmitter(String emitterName) . . . . . . . . . . . . . . . . . 162.2.20 void animator.setLightActive(String lightName, bool active) . . . . . . . . . . . . . . . 162.2.21 void animator.setLightPosition(String lightName, Vec2F position) . . . . . . . . . . . . 162.2.22 void animator.setLightColor(String lightName, Color color) . . . . . . . . . . . . . . . 162.2.23 void animator.setLightPointAngle(String lightName, float angle) . . . . . . . . . . . . 162.2.24 bool animator.hasSound(String soundName) . . . . . . . . . . . . . . . . . . . . . . . 162.2.25 void animator.setSoundPool(String soundName, List soundPool) . . . . . 172.2.26 void animator.setSoundPosition(String soundName, Vec2F position) . . . . . . . . . . 172.2.27 void animator.playSound(String soundName, [int loops = 0]) . . . . . . . . . . . . . 172.2.28 void animator.setSoundVolume(String soundName, float volume, [float rampTime

= 0.0]) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172.2.29 void animator.setSoundPitch(String soundName, float pitch, [float rampTime = 0.0]) 172.2.30 void animator.stopAllSounds(String soundName) . . . . . . . . . . . . . . . . . . . . . 172.2.31 void animator.setEffectActive(String effect, bool enabled) . . . . . . . . . . . . . . . 172.2.32 Vec2F animator.partPoly(String partName, String propertyName) . . . . . . . . . . . 172.2.33 PolyF animator.partPoly(String partName, String propertyName) . . . . . . . . . . . 18

2.3 config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.3.1 Json config.getParameter(String parameter, Json default) . . . . . . . . . . . . . . . . 18

2.4 entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.4.1 EntityId entity.id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

2.5 item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.5.1 String item.name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.5.2 size_t item.count() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.5.3 size_t item.setCount(size_t count) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.5.4 size_t item.maxStack() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.5.5 bool item.is(ItemDescriptor desc) . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.5.6 bool item.matches(ItemDescriptor desc) . . . . . . . . . . . . . . . . . . . . . . . . 202.5.7 Json item.matchingDescriptors() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.5.8 bool item.consume(size_t count) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.5.9 bool item.empty() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.5.10 ItemDescriptor item.descriptor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.5.11 String item.description() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

ii

2.5.12 String item.friendlyName() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.5.13 int item.rarity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.5.14 String item.rarityString() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.5.15 size_t item.price() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.5.16 unsigned item.fuelAmount() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.5.17 Json item.iconDrawables() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.5.18 Json item.dropDrawables() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.5.19 String item.largeImage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.5.20 String item.tooltipKind() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.5.21 String item.category() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.5.22 String item.pickupSound() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.5.23 bool item.twoHanded() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.5.24 float item.timeToLive() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.5.25 Json item.learnBlueprintsOnPickup() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.5.26 bool item.hasItemTag(String itemTag) . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.5.27 Json item.pickupQuestTemplates() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

2.6 mcontroller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.6.1 MovementParameters mcontroller.parameters() . . . . . . . . . . . . . . . . . . . . . 232.6.2 void mcontroller.applyParameters(Json parameters) . . . . . . . . . . . . . . . . . . . . 232.6.3 void mcontroller.resetParameters() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.6.4 Vec2F mcontroller.position() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.6.5 float mcontroller.xPosition() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.6.6 float mcontroller.yPosition() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.6.7 Vec2F mcontroller.velocity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.6.8 float mcontroller.xVelocity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.6.9 float mcontroller.yVelocity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.6.10 float mcontroller.rotation() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.6.11 PolyF mcontroller.collisionBody() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.6.12 RectF mcontroller.collisionBoundBox() . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.6.13 RectF mcontroller.localBoundBox() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.6.14 bool mcontroller.isColliding() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.6.15 bool mcontroller.isNullColliding() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.6.16 bool mcontroller.isCollisionStuck() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.6.17 float mcontroller.stickingDirection() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.6.18 float mcontroller.liquidPercentage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.6.19 LiquidId mcontroller.liquidId() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252.6.20 bool mcontroller.onGround() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.6.21 void mcontroller.setPosition(Vec2F position) . . . . . . . . . . . . . . . . . . . . . . . . 262.6.22 void mcontroller.setXPosition(float x) . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.6.23 void mcontroller.setYPosition(float y) . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.6.24 void mcontroller.translate(Vec2F direction) . . . . . . . . . . . . . . . . . . . . . . . . . 262.6.25 void mcontroller.setVelocity(Vec2F velocity) . . . . . . . . . . . . . . . . . . . . . . . . 262.6.26 void mcontroller.setXVelocity(Vec2F xVelocity) . . . . . . . . . . . . . . . . . . . . . . 262.6.27 void mcontroller.setYVelocity(Vec2F yVelocity) . . . . . . . . . . . . . . . . . . . . . . 262.6.28 void mcontroller.addMomentum(Vec2F momentum) . . . . . . . . . . . . . . . . . . . . 272.6.29 void mcontroller.setRotation(float angle) . . . . . . . . . . . . . . . . . . . . . . . . . 272.6.30 void mcontroller.rotate(float angle) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272.6.31 void mcontroller.accelerate(Vec2F acceleration) . . . . . . . . . . . . . . . . . . . . . . 272.6.32 void mcontroller.force(Vec2F force) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272.6.33 void mcontroller.approachVelocity(Vec2F targetVelocity, float maxControlForce) . . . 272.6.34 void mcontroller.approachVelocityAlongAngle(float angle, float targetVelocity,

float maxControlForce, bool positiveOnly = false) . . . . . . . . . . . . . . . . . . . . 272.6.35 void mcontroller.approachXVelocity(float targetVelocity, float maxControlForce) . . 272.6.36 void mcontroller.approachYVelocity(float targetVelocity, float maxControlForce) . . 28

iii

2.7 Json root.assetJson(String assetPath) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282.8 Json root.makeCurrentVersionedJson(String versioningIdentifier, Json content) . . . . . . . . . 282.9 Json root.loadVersionedJson(Json versionedContent, String versioningIdentifier) . . . . . . . . 282.10 double root.evalFunction(String functionName, double input) . . . . . . . . . . . . . . . . . 282.11 double root.evalFunction2(String functionName, double input1, double input2) . . . . . . . 282.12 Vec2U root.imageSize(String imagePath) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292.13 List root.imageSpaces(String imagePath, Vec2F worldPosition, float spaceScan,

bool flip) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292.14 RectU root.nonEmptyRegion(String imagePath) . . . . . . . . . . . . . . . . . . . . . . . . . . 292.15 Json root.npcConfig(String npcType) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292.16 float root.projectileGravityMultiplier(String projectileName) . . . . . . . . . . . . . . . . . . 292.17 Json root.projectileConfig(String projectileName) . . . . . . . . . . . . . . . . . . . . . . . . . 292.18 JsonArray root.recipesForItem(String itemName) . . . . . . . . . . . . . . . . . . . . . . . . 292.19 String root.itemType(String itemName) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302.20 JsonArray root.itemTags(String itemName) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302.21 bool root.itemHasTag(String itemName, String tagName) . . . . . . . . . . . . . . . . . . . 302.22 Json root.itemConfig(ItemDescriptor descriptor, [float level], [unsigned seed]) . . . . . 302.23 ItemDescriptor root.createItem(ItemDescriptor descriptor, [float level], [unsigned

seed]) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302.24 Json root.tenantConfig(String tenantName) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302.25 JsonArray root.getMatchingTenants(map colonyTags) . . . . . . . . . 302.26 JsonArray root.liquidStatusEffects(LiquidId liquid) . . . . . . . . . . . . . . . . . . . . . . . 312.27 table root.behaviorModule(String moduleName) . . . . . . . . . . . . . . . . . . . . . . . . . 312.28 String root.generateName(String assetPath, [unsigned seed]) . . . . . . . . . . . . . . . . . 312.29 Json root.questConfig(String questTemplateId) . . . . . . . . . . . . . . . . . . . . . . . . . . . 312.30 JsonArray root.npcPortrait(String portraitMode, String species, String npcType, float

level, [unsigned seed], [Json parameters]) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312.31 JsonArray root.monsterPortrait(String typeName, [Json parameters]) . . . . . . . . . . . . . 312.32 bool root.isTreasurePool(String poolName) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322.33 JsonArray root.createTreasure(String poolName, float level, [unsigned seed]) . . . . . . 322.34 String root.materialMiningSound(String materialName, [String modName]) . . . . . . . . . 322.35 String root.materialFootstepSound(String materialName, [String modName]) . . . . . . . . 322.36 status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

2.36.1 Json status.statusProperty(String name, Json default) . . . . . . . . . . . . . . . . . . 332.36.2 void status.setStatusProperty(String name, Json value) . . . . . . . . . . . . . . . . . 332.36.3 float status.stat(String statName) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332.36.4 bool status.statPositive(String statName) . . . . . . . . . . . . . . . . . . . . . . . . . 332.36.5 List status.resourceNames() . . . . . . . . . . . . . . . . . . . . . . . . . . . 332.36.6 bool status.isResource(String resourceName) . . . . . . . . . . . . . . . . . . . . . . . 332.36.7 float status.resource(String resourceName) . . . . . . . . . . . . . . . . . . . . . . . 332.36.8 bool status.resourcePositive(String resourceName) . . . . . . . . . . . . . . . . . . . . 332.36.9 void status.setResource(String resourceName, float value) . . . . . . . . . . . . . . 342.36.10 void status.modifyResource(String resourceName, float value) . . . . . . . . . . . . 342.36.11 float status.giveResource(String resourceName, float value) . . . . . . . . . . . . . 342.36.12 bool status.consumeResource(String resourceName, float amount) . . . . . . . . . . 342.36.13 bool status.overConsumeResource(String resourceName, float amount) . . . . . . . 342.36.14 bool status.resourceLocked(String resourceName) . . . . . . . . . . . . . . . . . . . . 342.36.15 void status.setResourceLocked(String resourceName, bool locked) . . . . . . . . . . . 342.36.16 void status.resetResource(String resourceName) . . . . . . . . . . . . . . . . . . . . . 342.36.17 void status.resetAllResources() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352.36.18 float status.resourceMax(String resourceName) . . . . . . . . . . . . . . . . . . . . . 352.36.19 float status.resourcePercentage(String resourceName) . . . . . . . . . . . . . . . . . . 352.36.20 void status.setResourcePercentage(String resourceName, float value) . . . . . . . . . 352.36.21 void status.modifyResourcePercentage(String resourceName, float value) . . . . . . 35

iv

2.36.22 JsonArray status.getPersistentEffects(String effectCategory) . . . . . . . . . . . . . . 352.36.23 void status.addPersistentEffect(String effectCategory, Json effect) . . . . . . . . . . . 352.36.24 void status.addPersistentEffects(String effectCategory, JsonArray effects) . . . . . . 352.36.25 void status.setPersistentEffects(String effectCategory, JsonArray effects) . . . . . . . 362.36.26 void status.clearPersistentEffects(String effectCategory) . . . . . . . . . . . . . . . . . 362.36.27 void status.clearAllPersistentEffects() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362.36.28 void status.addEphemeralEffect(String effectName, [float duration], [EntityId

sourceEntity]) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362.36.29 void status.addEphemeralEffects(JsonArray effects, [EntityId sourceEntity]) . . . . 362.36.30 void status.removeEphemeralEffect(String effectName) . . . . . . . . . . . . . . . . . 362.36.31 void status.clearEphemeralEffects() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362.36.32 List, uint64_t sta-

tus.damageTakenSince([uint64_t since = 0]]) . . . . . . . . . . . . . . . . . . . . . . . 372.36.33 List, uint64_t sta-

tus.inflictedHitsSince([uint64_t since = 0]]) . . . . . . . . . . . . . . . . . . . . . . . . 372.36.34 List, uint65_t status.functionName([uint64_t since =

0]) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372.37 float world.magnitude(Vec2F position1, Vec2F position2) . . . . . . . . . . . . . . . . . . . . 372.38 Vec2F world.distance(Vec2F position1, Vec2F position2) . . . . . . . . . . . . . . . . . . . . . . 372.39 bool world.polyContains(PolyF poly, Vec2F position) . . . . . . . . . . . . . . . . . . . . . . . 382.40 Vec2F world.xwrap(Vec2F position) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382.41 float world.xwrap(float xPosition) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382.42 Variant world.nearestTo(Variant sourcePosition,

Variant targetPosition) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382.43 bool world.pointCollision(Vec2F point, [CollisionSet collisionKinds]) . . . . . . . . . . . . 382.44 bool world.pointTileCollision(Vec2F point, [CollisionSet collisionKinds]) . . . . . . . . . . 382.45 bool world.lineCollision(Vec2F startPoint, Vec2F endPoint, [CollisionSet collisionKinds]) . 392.46 bool world.lineTileCollision(Vec2F startPoint, Vec2F endPoint, [CollisionSet collisionKinds]) 392.47 bool world.rectCollision(RectF rect, [CollisionSet collisionKinds]) . . . . . . . . . . . . . . 392.48 bool world.rectTileCollision(RectF rect, [CollisionSet collisionKinds]) . . . . . . . . . . . . 392.49 bool world.polyCollision(PolyF poly, [Vec2F position], [CollisionSet collisionKinds]) . . . 392.50 List world.collisionBlocksAlongLine(Vec2F startPoint, Vec2F endPoint,

[CollisionSet collisionKinds], [int maxReturnCount]) . . . . . . . . . . . . . . . . . . . . . . 392.51 List world.liquidAlongLine(Vec2F startPoint, Vec2F end-

Point) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402.52 Vec2F world.resolvePolyCollision(PolyF poly, Vec2F position, float maximumCorrection,

[CollisionSet collisionKinds]) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402.53 bool world.tileIsOccupied(Vec2I tilePosition, [bool foregroundLayer], [bool includeEphemeral]) 402.54 bool world.placeObject(String objectName, Vec2I tilePosition, [int direction], [Json param-

eters]) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402.55 EntityId world.spawnItem(ItemDescriptor item, Vec2F position, [unsigned count],

[Json parameters]) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402.56 List world.spawnTreasure(Vec2F position, String poolName, float level,

[unsigned seed]) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412.57 EntityId world.spawnMonster(String monsterType, Vec2F position, [Json parameters]) . . . 412.58 EntityId world.spawnNpc(Vec2F position, String npcType, String species, float level,

[unsigned seed], [Json parameters]) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412.59 EntityId world.spawnStagehand(Vec2F position, String type, [Json overrides]) . . . . . . . 412.60 EntityId world.spawnProjectile(String projectileName, Vec2F position, [EntityId

sourceEntityId], [Vec2F direction], [bool trackSourceEntity], [Json parameters]) . . . . . . . . . 412.61 EntityId world.spawnVehicle(String vehicleName, Vec2F position, [Json overrides]) . . . . 422.62 double world.time() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422.63 unsigned world.day() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422.64 double world.timeOfDay() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

v

2.65 float world.dayLength() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422.66 Json world.getProperty(String propertyName, [Json defaultValue]) . . . . . . . . . . . . . . . 422.67 void world.setProperty(String propertyName, Json value) . . . . . . . . . . . . . . . . . . . . 422.68 LiquidLevel world.liquidAt(Vec2I position) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432.69 LiquidLevel world.liquidAt(RectF region) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432.70 float world.gravity(Vec2F position) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432.71 bool world.spawnLiquid(Vec2F position, LiquidId liquid, float quantity) . . . . . . . . . . . 432.72 LiquidLevel world.destroyLiquid(Vec2F position) . . . . . . . . . . . . . . . . . . . . . . . . 432.73 bool world.isTileProtected(Vec2F position) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432.74 PlatformerAStar::Path world.findPlatformerPath(Vec2F startPosition, Vec2F endPosition,

ActorMovementParameters movementParameters, PlatformerAStar::ParameterssearchParameters) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

2.75 PlatformerAStar::PathFinder world.platformerPathStart(Vec2F startPosi-tion, Vec2F endPosition, ActorMovementParameters movementParameters,PlatformerAStar::Parameters searchParameters) . . . . . . . . . . . . . . . . . . . . . . 442.75.1 bool explore([int nodeLimit]) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442.75.2 PlatformerAStar::Path result() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

2.76 float world.lightLevel(Vec2F position) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442.77 float world.windLevel(Vec2F position) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442.78 bool world.breathable(Vec2F position) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442.79 bool world.underground(Vec2F position) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442.80 Variant world.material(Vec2F position, String layerName) . . . . . . . . 452.81 String world.mod(Vec2F position, String layerName) . . . . . . . . . . . . . . . . . . . . . . 452.82 bool world.damageTiles(List positions, String layerName, Vec2F sourcePosition,

String damageType, float damageAmount, [unsigned harvestLevel]) . . . . . . . . . . . . . 452.83 bool world.damageTileArea(Vec2F center, float radius, String layerName, Vec2F sourcePo-

sition, String damageType, float damageAmount, [unsigned harvestLevel) . . . . . . . . . . 452.84 bool world.placeMaterial(Vec2I position, String layerName, String materialName, [int

hueShift], [bool allowOverlap]) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452.85 bool world.placeMod(Vec2I position, String layerName, String modName, [int hueShift],

[bool allowOverlap]) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462.86 List world.entityQuery(Vec2F position, Variant

2.100 String world.entityType(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482.101 Vec2F world.entityPosition(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . . . . . . 482.102 Vec2F world.entityVelocity(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . . . . . . 492.103 unsigned world.entityMoney(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . . . . 492.104 unsigned world.entityHasCountOfItem(EntityId entityId, String itemName) . . . . . . . . . 492.105 Vec2F world.entityHealth(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492.106 String world.entitySpecies(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . . . . . . 492.107 String world.entityGender(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . . . . . . 492.108 String world.entityName(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . . . . . . 492.109 String world.entityDescription(EntityId entityId, [String species]) . . . . . . . . . . . . . . 502.110 JsonArray world.entityPortrait(EntityId entityId, String portraitMode) . . . . . . . . . . . 502.111 String world.entityHandItem(EntityId entityId, String handName) . . . . . . . . . . . . . . 502.112 ItemDescriptor world.entityHandItemDescriptor(EntityId entityId, String handName) . . 502.113 String world.entityUniqueId(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . . . . . 502.114 Jsonworld.getObjectParameter(EntityId entityId, String parameterName, [Json defaultValue]) 502.115 List world.objectSpaces(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . . 512.116 int world.farmableStage(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512.117 int world.containerSize(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512.118 bool world.containerClose(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . . . . . . 512.119 bool world.containerOpen(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . . . . . . 512.120 JsonArray world.containerItems(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . . 512.121 ItemDescriptor world.containerItemAt(EntityId entityId, unsigned offset) . . . . . . . . 512.122 bool world.containerConsume(EntityId entityId, ItemDescriptor item) . . . . . . . . . . . 522.123 bool world.containerConsumeAt(EntityId entityId, unsigned offset, unsigned count) . . . 522.124 unsigned world.containerAvailable(EntityId entityId, ItemDescriptor item) . . . . . . . . 522.125 JsonArray world.containerTakeAll(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . 522.126 ItemDescriptor world.containerTakeAt(EntityId entityId, unsigned offset) . . . . . . . . 522.127 ItemDescriptor world.containerTakeNumItemsAt(EntityId entityId, unsigned offset,

unsigned count) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522.128 unsigned world.containerItemsCanFit(EntityId entityId, ItemDescriptor item) . . . . . . 532.129 Json world.containerItemsFitWhere(EntityId entityId, ItemDescriptor items) . . . . . . . 532.130 ItemDescriptor world.containerAddItems(EntityId entityId, ItemDescriptor items) . . 532.131 ItemDescriptor world.containerStackItems(EntityId entityId, ItemDescriptor items) . 532.132 ItemDescriptor world.containerPutItemsAt(EntityId entityId, ItemDescriptor items,

unsigned offset) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532.133 ItemDescriptor world.containerItemApply(EntityId entityId, ItemDescriptor items,

unsigned offset) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532.134 ItemDescriptor world.containerSwapItemsNoCombine(EntityId entityId,

ItemDescriptor items, unsigned offset) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542.135 ItemDescriptor world.containerSwapItems(EntityId entityId, ItemDescriptor items,

unsigned offset) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542.136 LuaValue world.callScriptedEntity(EntityId entityId, String functionName, [LuaValue

args ...]) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542.137 RpcPromise world.sendEntityMessage(Variant entityId,

String messageType, [LuaValue args ...]) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542.138 RpcPromise world.findUniqueEntity(String‘ uniqueId) . . . . . . . . . . . . 542.139 bool world.loungeableOccupied(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . . . 552.140 bool world.isMonster(EntityId entityId, [bool aggressive]) . . . . . . . . . . . . . . . . . . . 552.141 String world.monsterType(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . . . . . . 552.142 bool world.isNpc(EntityId entityId, [int damageTeam]) . . . . . . . . . . . . . . . . . . . . . 552.143 String world.npcType(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552.144 String world.stagehandType(EntityId entityId) . . . . . . . . . . . . . . . . . . . . . . . . . . 552.145 void world.debugPoint(Vec2F position, Color color) . . . . . . . . . . . . . . . . . . . . . . . . 552.146 void world.debugLine(Vec2F startPosition, Vec2F endPosition, Color color) . . . . . . . . . . 56

vii

2.147 void world.debugPoly(PolyF poly, Color color) . . . . . . . . . . . . . . . . . . . . . . . . . . 562.148 void world.debugText(String formatString, [LuaValue formatValues ...], Vec2F position,

Color color) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562.149 bool world.breakObject(EntityId entityId, bool smash) . . . . . . . . . . . . . . . . . . . . . 562.150 bool world.isVisibleToPlayer(RectF region) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562.151 bool world.loadRegion(RectF region) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562.152 bool world.regionActive(RectF region) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572.153 void world.setTileProtection(DungeonId dungeonId, bool protected) . . . . . . . . . . . . . . . 572.154 DungeonId world.dungeonId(Vec2F position) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572.155 bool world.isPlayerModified(RectI region) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572.156 LiquidLevel world.forceDestroyLiquid(Vec2F position) . . . . . . . . . . . . . . . . . . . . . 572.157 EntityId world.loadUniqueEntity(String uniqueId) . . . . . . . . . . . . . . . . . . . . . . . . 572.158 void world.setUniqueId(EntityId entityId, [String uniqueId]) . . . . . . . . . . . . . . . . . 572.159 ItemDescriptor world.takeItemDrop(EntityId targetEntityId, [EntityId sourceEntityId]) . 582.160 void world.setPlayerStart(Vec2F position, [bool respawnInWorld]) . . . . . . . . . . . . . . . . 582.161 List world.players() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

viii

Starbound Documentation, Release 1.0

This is the unofficial documentation consisting of the official documentation on a readthedocs page, because it’s easierto view and search.

Contents 1


2 Contents

CHAPTER 1

What is starbound

Starbound is a space exploration game on a 2D side scrolling plane. It can be played single player or multiplayer andcan be modified in many ways.

3


4 Chapter 1. What is starbound

CHAPTER 2

Documentation

Contents:

actor mcontroller

The mcontroller table sometimes contains functions relating to the actor movement controller.

This section of mcontroller documentation refers to the ActorMovementController lua bindings. There is other docu-mentation referring to the mcontroller table for base MovementControllers.

• monsters

• npcs

• tech

• companion system scripts

• status effects

• quest scripts

• active items

RectF mcontroller.boundBox()

Returns a rect containing the entire collision of the movement controller, in local coordinates.

5


PolyF mcontroller.collisionPoly()

Returns the collision poly of the movement controller, in local coordinates.

PolyF mcontroller.collisionBody()

Returns the collision poly of the movement controller, in world coordinates.

Vec2F mcontroller.position()

Returns the current position of the movement controller.

float mcontroller.xPosition()

Returns the current horizontal position of the movement controller.

float mcontroller.yPosition()

Returns the current vertical position of the movement controller.

Vec2F mcontroller.velocity()

Returns the current velocity of the movement controller.

float mcontroller.xVelocity()

Returns the current horizontal speed of the movement controller.

float mcontroller.yVelocity()

Returns the current vertical speed of the movement controller.

6 Chapter 2. Documentation


float mcontroller.rotation()

Returns the current rotation of the movement controller in radians.

bool mcontroller.isColliding()

Returns whether the movement controller is currently colliding with world geometry or a PhysicsMovingCollision.

bool mcontroller.isNullColliding()

Returns whether the movement controller is currently colliding with null world geometry. Null collision occurs inunloaded sectors.

bool mcontroller.isCollisionStuck()

Returns whether the movement controller is currently stuck colliding. Movement controllers can stick if thestickyCollision movement parameter is set.

float mcontroller.stickingDirection()

Returns the angle that the movement controller is currently stuck at, in radians.

float mcontroller.liquidPercentage()

Returns the percentage of the collision poly currently submerged in liquid;

LiquidId mcontroller.liquidId()

Returns the liquid ID of the liquid that the movement controller is currently submerged in. If this is several liquids thisreturns the most plentiful one.

bool mcontroller.onGround()

Returns whether the movement controller is currently on ground.

2.1. actor mcontroller 7


void mcontroller.setAnchorState(EntityId anchorableEntity, size_t anchorPosition)

Anchors the movement controller to an anchorable entity at the given anchor index.

void mcontroller.resetAnchorState()

Reset the anchor state.

EntityId, int mcontroller.anchorState()

Returns ID of anchored entity and index of the anchor position.

void mcontroller.setPosition(Vec2F position)

Sets the position of the movement controller.

void mcontroller.setXPosition(float x)

Sets the horizontal position of the movement controller.

void mcontroller.setYPosition(float y)

Sets the vertical position of the movement controller.

void mcontroller.translate(Vec2F direction)

Moves the movement controller by the vector provided.

void mcontroller.setVelocity(Vec2F velocity)

Sets the velocity of the movement controller.



void mcontroller.setXVelocity(Vec2F xVelocity)

Sets the horizontal velocity of the movement controller.

void mcontroller.setYVelocity(Vec2F yVelocity)

Sets the vertical velocity of the movement controller.

void mcontroller.addMomentum(Vec2F momentum)

Adds (momentum / mass) velocity to the movement controller.

void mcontroller.setRotation(float angle)

Sets the rotation of the movement controller. Angle is in radians.

ActorMovementParameters mcontroller.baseParameters()

Returns the base movement parameters.

bool mcontroller.walking()

Returns whether the actor movement controller is currently walking.

bool mcontroller.running()

Returns whether the actor movement controller is currently running.

int mcontroller.movingDirection()

Returns the direction that the actor movement controller is currently moving in. -1 for left, 1 for right.



int mcontroller.facingDirection()

Returns the facing direction. -1 for left, 1 for right.

bool mcontroller.crouching()

Returns whether the controller is currently crouching.

bool mcontroller.flying()

Returns whether the controller is currently flying.

bool mcontroller.falling()

Returns whether the controller is currently falling.

bool mcontroller.canJump()

Returns whether the controller can currently jump.

bool mcontroller.groundMovement()

Returns whether the controller is currently in a ground movement state. Movement controllers can be in groundmovement even when onGround returns false.

bool mcontroller.liquidMovement()

Returns whether the controller is currently in liquid movement mode.

controls

The actor movement controller has a set of controls. Controls can be set anywhere and are accumulated and evaluatedafter all scripts are run. Controls will either override previously set controls, or combine them.

Controls are either cleared before every script update, or can be set to be manually cleared.



void mcontroller.controlRotation(float rotation)

Rotates the controller. Each control adds to the previous one.

void mcontroller.controlAcceleration(Vec2F acceleration)

Controls acceleration. Each control adds to the previous one.

void mcontroller.controlForce()

Controls force. Each control adds to the previous one.

void mcontroller.controlApproachVelocity(Vec2F targetVelocity, float maxControlForce)

Approaches the targetVelocity using the force provided. If the current velocity is higher than the provided targetVe-locity, the targetVelocity will still be approached, effectively slowing down the entity.

Each control overrides the previous one.

void mcontroller.controlApproachVelocityAlongAngle(float angle, float tar-getVelocity, float maxControlForce, bool positiveOnly = false)

Approaches the targetVelocity but only along the provided angle, not affecting velocity in the perpendicular axis. IfpositiveOnly, then it will not slow down the movementController if it is already moving faster than targetVelocity.


void mcontroller.controlApproachXVelocity(float targetVelocity, float maxCon-trolForce)

Approaches an X velocity. Same as using approachVelocityAlongAngle with angle 0.


void mcontroller.controlApproachYVelocity(float targetVelocity, float maxCon-trolForce)

Approaches a Y velocity. Same as using approachVelocityAlongAngle with angle (Pi / 2).




void mcontroller.controlParameters(ActorMovementParameters parameters)

Changes movement parameters. Parameters are merged into the base parameters.

Each control is merged into the previous one.

void mcontroller.controlModifiers(ActorMovementModifiers modifiers)

Changes movement modifiers. Modifiers are merged into the base modifiers.

Each control is merged into the previous one.

void mcontroller.controlMove(float direction, bool run)

Controls movement in a direction.

Each control replaces the previous one.

void mcontroller.controlFace(float direction)

Controls the facing direction.

Each control replaces the previous one.

void mcontroller.controlDown()

Controls dropping through platforms.

void mcontroller.controlCrouch()

Controls crouching.

void mcontroller.controlJump()

Controls starting a jump. Only has an effect if canJump is true.



void mcontroller.controlHoldJump()

Keeps holding jump. Will not trigger a new jump, and can be held in the air.

void mcontroller.controlFly(Vec2F velocity)

Controls flying in the specified velocity.


bool mcontroller.autoClearControls()

Returns whether the controller is currently set to auto clear controls before each script update.

void mcontroller.setAutoClearControls(bool enabled)

Set whether to automatically clear controls before each script update.

void mcontroller.clearControls()

Manually clear all controls.

animator

The animator table contains functions that relate to an attached networked animator. Networked animators are foundin:

• tech

• monsters

• vehicles

• status effects

• active items

bool animator.setAnimationState(String stateType, String State, bool startNew= false)

Sets an animation state. If startNew is true, restart the animation loop if it’s already active. Returns whether the statewas set.

2.2. animator 13


String animator.animationState(String stateType)

Returns the current state for a state type.

Json animator.animationStateProperty(String stateType, String propertyName)

Returns the value of the specified property for a state type.

void animator.setGlobalTag(String tagName, String tagValue)

Sets a global animator tag. A global tag replaces any tag with the specified tagValue across all animation parts.

void animator.setPartTag(String partType, String tagName, String tagValue)

Sets a local animator tag. A part tag replaces any tag with the specified tagValue in the partType animation part only.

void animator.setAnimationRate(float rate)

Sets the animation rate of the animator.

void animator.rotateGroup(String rotationGroup, float targetAngle, bool imme-diate)

Rotates a rotation group to the specified angle. If immediate, ignore rotation speed.

NOTE: Rotation groups have largely been replaced by transformation groups and should only be used in a contextwhere maintaining a rotation speed is important. When possible use transformation groups.

float animator.currentRotationAngle(String rotationGroup)

Returns the current angle for a rotation group.

bool animator.hasTransformationGroup(String transformationGroup)

Returns whether the animator contains the specified transformation group.



void animator.translateTransformationGroup(String transformationGroup, Vec2Ftranslate)

Translates the specified transformation group.

void animator.rotateTransformationGroup(String transformationGroup, floatrotation)

Rotates the specified transformation group.

void animator.scaleTransformationGroup(String transformationGroup, floatscale, [Vec2F scaleCenter])

Scales the specified transformation group. Optionally scale it from a scaleCenter.

void animator.transformTransformationGroup(String transformationGroup,float a, float b, float c, float d, float tx, float ty)

Applies a custom Mat3 transform to the specified transformationGroup. The applied matrix will be:

[a, b, tx, c, d, ty, 0, 0, 1]

void animator.resetTransformationGroup(String transformationGroup)

Resets a transformationGroup to the identity transform.

[1, 0, 0 0, 1, 0, 0, 1, 1]

void animator.setParticleEmitterActive(String emitterName, bool active)

Sets a particle emitter to be active or inactive.

void animator.setParticleEmitterEmissionRate(String emitterName, float emis-sionRate)

Sets the rate at which a particle emitter emits particles while active.

2.2. animator 15


void animator.setParticleEmitterBurstCount(String emitterName, unsignedburstCount)

Sets the amount of each particle the emitter will emit when using burstParticleEmitter.

void animator.setParticleEmitterOffsetRegion(String emitterName, RectF offse-tRegion)

Sets an offset region for the particle emitter. Any particles spawned will have a randomized offset within the regionadded to their position.

void animator.burstParticleEmitter(String emitterName)

Spawns the entire set of particles burstCount times, where burstCount can be configured in the animator or setby setParticleEmitterBurstCount.

void animator.setLightActive(String lightName, bool active)

Sets a light to be active/inactive.

void animator.setLightPosition(String lightName, Vec2F position)

Sets the position of a light.

void animator.setLightColor(String lightName, Color color)

Sets the color of a light. Brighter color gives a higher light intensity.

void animator.setLightPointAngle(String lightName, float angle)

Sets the angle of a pointLight.

bool animator.hasSound(String soundName)

Returns whether the animator has a sound by the name of soundName



void animator.setSoundPool(String soundName, List soundPool)

Sets the list of sound assets to pick from when playing a sound.

void animator.setSoundPosition(String soundName, Vec2F position)

Sets the position that a sound is played at.

void animator.playSound(String soundName, [int loops = 0])

Plays a sound. Optionally loop loops times. 0 plays the sound once (no loops), -1 loops indefinitely.

void animator.setSoundVolume(String soundName, float volume, [float ramp-Time = 0.0])

Sets the volume of a sound. Optionally smoothly transition the volume over rampTime seconds.

void animator.setSoundPitch(String soundName, float pitch, [float rampTime= 0.0])

Sets the relative pitch of a sound. Optionally smoothly transition the pitch over rampTime seconds.

void animator.stopAllSounds(String soundName)

Stops all instances of the specified sound.

void animator.setEffectActive(String effect, bool enabled)

Sets a configured effect to be active/inactive.

Vec2F animator.partPoly(String partName, String propertyName)

Returns a Vec2F configured in a part’s properties with all of the part’s transformations applied to it.

2.2. animator 17


PolyF animator.partPoly(String partName, String propertyName)

Returns a PolyF configured in a part’s properties with all the part’s transformations applied to it.

config

The config lua bindings relate to anything that has a configuration and needs to access configuration parameters.

Json config.getParameter(String parameter, Json default)

Returns the value for the specified config parameter. If there is no value set, returns the default.

entity

The entity table contains functions that are common among all entities. Every function refers to the entity the scriptcontext is running on.

Accessible in:


• quests

• tech

• primary status script

• status effects

• monsters

• npcs

• objects

EntityId entity.id()

Returns the id number of the entity.

LuaTable entity.damageTeam()

Returns a table of the entity’s damage team type and team number. Ex: {type = “enemy”, team = 0}



bool entity.isValidTarget(EntityId entityId)

Returns whether the provided entity is a valid target of the current entity. An entity is a valid target if they can bedamaged, and in the case of monsters and NPCs if they are aggressive.

Vec2F entity.distanceToEntity(EntityId entityId)

Returns the vector distance from the current entity to the provided entity.

bool entity.entityInSight(EntityId entityId)

Returns whether the provided entity is in line of sight of the current entity.

Vec2F entity.position()

Returns the position of the current entity.

String entity.entityType()

Returns the type of the current entity.

String entity.uniqueId()

Returns the unique ID of the entity. Returns nil if there is no unique ID.

item

The item table is available in all scripted items and contains functions relating to the item itself.

String item.name()

Returns the name of the item.

2.5. item 19


size_t item.count()

Returns the stack count of the item.

size_t item.setCount(size_t count)

Sets the item count. Returns any overflow.

size_t item.maxStack()

Returns the max number of this item that will fit in a stack.

bool item.is(ItemDescriptor desc)

Returns whether the item is the same item type as the specified item.

bool item.matches(ItemDescriptor desc)

Returns whether the item matches the specified item, using the item’s internal matching descriptors.

Json item.matchingDescriptors()

Returns the list of matching descriptors.

bool item.consume(size_t count)

Consumes items from the stack. Returns whether the full count was successfuly consumed.

bool item.empty()

Returns whether the item stack is empty.



ItemDescriptor item.descriptor()

Returns an item descriptor for the item.

String item.description()

Returns the description for the item.

String item.friendlyName()

Returns the short description for the item.

int item.rarity()

Returns the rarity for the item.

• 0 = common

• 1 = uncommon

• 2 = rare

• 3 = legendary

• 4 = essential

String item.rarityString()

Returns the rarity as a string.

size_t item.price()

Returns the item price.

unsigned item.fuelAmount()

Returns the item fuel amount.

2.5. item 21


Json item.iconDrawables()

Returns a list of the item’s icon drawables.

Json item.dropDrawables()

Returns a list of the item’s itemdrop drawables.

String item.largeImage()

Returns the item’s configured large image, if any.

String item.tooltipKind()

Returns the item’s tooltip kind.

String item.category()

Returns the item’s category

String item.pickupSound()

Returns the item’s pickup sound.

bool item.twoHanded()

Returns whether the item is two handed.

float item.timeToLive()

Returns the items’s time to live.



Json item.learnBlueprintsOnPickup()

Returns a list of the blueprints learned on picking up this item.

bool item.hasItemTag(String itemTag)

Returns whether the set of item tags for this item contains the specified tag.

Json item.pickupQuestTemplates()

Returns a list of quests acquired on picking up this item.

mcontroller

The mcontroller table contains functions relating to the movement controller.

This section of mcontroller documentation refers to the MovementController lua bindings. Other documentation mayrefer to ActorMovementController lua bindings. MovementController is used in:

• projectiles

• vehicles

MovementParameters mcontroller.parameters()

Returns a table containing the movement parameters for the movement controller.

void mcontroller.applyParameters(Json parameters)

Applies the given parameters to the movement controller. The provided parameters are merged into the current move-ment parameters.

void mcontroller.resetParameters()

Resets movement parameters to their original state.

2.6. mcontroller 23


Vec2F mcontroller.position()

Returns the current position of the movement controller.

float mcontroller.xPosition()

Returns the current horizontal position of the movement controller.

float mcontroller.yPosition()

Returns the current vertical position of the movement controller.

Vec2F mcontroller.velocity()

Returns the current velocity of the movement controller.

float mcontroller.xVelocity()

Returns the current horizontal speed of the movement controller.

float mcontroller.yVelocity()

Returns the current vertical speed of the movement controller.

float mcontroller.rotation()

Returns the current rotation of the movement controller in radians.

PolyF mcontroller.collisionBody()

Returns the collision poly of the movement controller, in world coordinates.



RectF mcontroller.collisionBoundBox()

Returns a rect containing the entire collision poly of the movement controller, in world coordinates.

RectF mcontroller.localBoundBox()

Returns a rect containing the entire collision of the movement controller, in local coordinates.

bool mcontroller.isColliding()

Returns whether the movement controller is currently colliding with world geometry or a PhysicsMovingCollision.

bool mcontroller.isNullColliding()

Returns whether the movement controller is currently colliding with null world geometry. Null collision occurs inunloaded sectors.

bool mcontroller.isCollisionStuck()

Returns whether the movement controller is currently stuck colliding. Movement controllers can stick if thestickyCollision movement parameter is set.

float mcontroller.stickingDirection()

Returns the angle that the movement controller is currently stuck at, in radians.

float mcontroller.liquidPercentage()

Returns the percentage of the collision poly currently submerged in liquid;

LiquidId mcontroller.liquidId()

Returns the liquid ID of the liquid that the movement controller is currently submerged in. If this is several liquids thisreturns the most plentiful one.

2.6. mcontroller 25


bool mcontroller.onGround()

Returns whether the movement controller is currently on ground.

void mcontroller.setPosition(Vec2F position)

Sets the position of the movement controller.

void mcontroller.setXPosition(float x)

Sets the horizontal position of the movement controller.

void mcontroller.setYPosition(float y)

Sets the vertical position of the movement controller.

void mcontroller.translate(Vec2F direction)

Moves the movement controller by the vector provided.

void mcontroller.setVelocity(Vec2F velocity)

Sets the velocity of the movement controller.

void mcontroller.setXVelocity(Vec2F xVelocity)

Sets the horizontal velocity of the movement controller.

void mcontroller.setYVelocity(Vec2F yVelocity)

Sets the vertical velocity of the movement controller.



void mcontroller.addMomentum(Vec2F momentum)

Adds (momentum / mass) velocity to the movement controller.

void mcontroller.setRotation(float angle)

Sets the rotation of the movement controller. Angle is in radians.

void mcontroller.rotate(float angle)

Rotates the movement controller by an angle relative to its current angle. Angle is in radians.

void mcontroller.accelerate(Vec2F acceleration)

Accelerates the movement controller by the given acceleration for one tick.

void mcontroller.force(Vec2F force)

Accelerates the movement controller by (force / mass) for one tick.

void mcontroller.approachVelocity(Vec2F targetVelocity, float maxControlForce)

Approaches the targetVelocity using the force provided. If the current velocity is higher than the provided targetVe-locity, the targetVelocity will still be approached, effectively slowing down the entity.

void mcontroller.approachVelocityAlongAngle(float angle, float targetVelocity,float maxControlForce, bool positiveOnly = false)

Approaches the targetVelocity but only along the provided angle, not affecting velocity in the perpendicular axis. IfpositiveOnly, then it will not slow down the movementController if it is already moving faster than targetVelocity.

void mcontroller.approachXVelocity(float targetVelocity, float maxControl-Force)

Approaches an X velocity. Same as using approachVelocityAlongAngle with angle 0.

2.6. mcontroller 27


void mcontroller.approachYVelocity(float targetVelocity, float maxControl-Force)

Approaches a Y velocity. Same as using approachVelocityAlongAngle with angle (Pi / 2).

The root table contains functions that reference the game’s currently loaded assets and don’t relate to any morespecific context such as a particular world or universe.

Json root.assetJson(String assetPath)

Returns the contents of the specified JSON asset file.

Json root.makeCurrentVersionedJson(String versioningIdentifier,Json content)

Returns a versioned JSON representation of the given JSON content with the given identifier and the most recentversion as specified in versioning.config.

Json root.loadVersionedJson(Json versionedContent, String ver-sioningIdentifier)

Returns the given JSON content and identifier after applying appropriate versioning scripts to bring it up to the mostrecent version as specified in versioning.config.

double root.evalFunction(String functionName, double input)

Returns the evaluation of the specified univariate function (as defined in a .functions file) for the given inputvalue.

double root.evalFunction2(String functionName, double input1,double input2)

Returns the evaluation of the specified bivariate function (as defined in a .2functions file) for the given inputvalues.



Vec2U root.imageSize(String imagePath)

Returns the pixel dimensions of the specified image asset.

List root.imageSpaces(String imagePath, Vec2F worldPo-sition, float spaceScan, bool flip)

Returns a list of the world tile spaces the image would occupy if placed at the given position using the specifiedspaceScan value (the portion of a space that must be non-transparent for that space to count as filled).

RectU root.nonEmptyRegion(String imagePath)

Returns the rectangle containing the portion of the specified asset image that is non-transparent.

Json root.npcConfig(String npcType)

Returns a representation of the generated JSON configuration for an NPC of the given type.

float root.projectileGravityMultiplier(String projectileName)

Returns the gravity multiplier of the given projectile’s movement controller configuration as configured in physics.config.

Json root.projectileConfig(String projectileName)

Returns a representation of the JSON configuration for the given projectile.

JsonArray root.recipesForItem(String itemName)

Returns a list of JSON configurations of all recipes which output the given item.

2.12. Vec2U root.imageSize(String imagePath) 29


String root.itemType(String itemName)

Returns the item type name for the specified item.

JsonArray root.itemTags(String itemName)

Returns a list of the tags applied to the specified item.

bool root.itemHasTag(String itemName, String tagName)

Returns true if the given item’s tags include the specified tag and false otherwise.

Json root.itemConfig(ItemDescriptor descriptor, [float level],[unsigned seed])

Generates an item from the specified descriptor, level and seed and returns a JSON object containing the directory,config and parameters for that item.

ItemDescriptor root.createItem(ItemDescriptor descriptor,[float level], [unsigned seed])

Generates an item from the specified descriptor, level and seed and returns a new item descriptor for the resulting item.

Json root.tenantConfig(String tenantName)

Returns the JSON configuration for the given tenant.

JsonArray root.getMatchingTenants(mapcolonyTags)

Returns an array of JSON configurations of tenants matching the given map of colony tags and corresponding objectcounts.



JsonArray root.liquidStatusEffects(LiquidId liquid)

Returns an array of status effects applied by the given liquid.

table root.behaviorModule(String moduleName)

Returns a table for the given behavior module containing its name, a list of scripts, the JSON root node of thatmodule, and a list of parameters that the module accepts.

String root.generateName(String assetPath, [unsigned seed])

Returns a randomly generated name using the specified name gen config and seed.

Json root.questConfig(String questTemplateId)

Returns the JSON configuration of the specified quest template.

JsonArray root.npcPortrait(String portraitMode, String species,String npcType, float level, [unsigned seed], [Json parame-ters])

Generates an NPC with the specified type, level, seed and parameters and returns a portrait in the given portraitModeas a list of drawables.

JsonArray root.monsterPortrait(String typeName, [Json parame-ters])

Generates a monster of the given type with the given parameters and returns its portrait as a list of drawables.

2.26. JsonArray root.liquidStatusEffects(LiquidId liquid) 31


bool root.isTreasurePool(String poolName)

Returns true if the given treasure pool exists and false otherwise. Can be used to guard against errors attempting togenerate invalid treasure.

JsonArray root.createTreasure(String poolName, float level,[unsigned seed])

Generates an instance of the specified treasure pool, level and seed and returns the contents as a list of item descriptors.

String root.materialMiningSound(String materialName, [StringmodName])

Returns the path of the mining sound asset for the given material and mod combination, or nil if no mining sound isset.

String root.materialFootstepSound(String materialName, [StringmodName])

Returns the path of the footstep sound asset for the given material and mod combination, or nil if no footstep soundis set.

status

The status table relates to the status controller attached to an entity. It is available in:

• monsters

• npcs

• status effects


• quest scripts

• tech

• primary status scripts for: player, monster, npc



Json status.statusProperty(String name, Json default)

Returns the value assigned to the specified status property. If there is no value set, returns default.

void status.setStatusProperty(String name, Json value)

Sets a status property to the specified value.

float status.stat(String statName)

Returns the value for the specified stat. Defaults to 0.0 if the stat does not exist.

bool status.statPositive(String statName)

Returns whether the stat value is greater than 0.

List status.resourceNames()

Returns a list of the names of all the configured resources;

bool status.isResource(String resourceName)

Returns whether the specified resource exists in this status controller.

float status.resource(String resourceName)

Returns the value of the specified resource.

bool status.resourcePositive(String resourceName)

Returns whether the value of the specified resource is greater than 0.

2.36. status 33


void status.setResource(String resourceName, float value)

Sets a resource to the specified value.

void status.modifyResource(String resourceName, float value)

Adds the specified value to a resource.

float status.giveResource(String resourceName, float value)

Adds the specified value to a resource. Returns any overflow.

bool status.consumeResource(String resourceName, float amount)

Tries to consume the specified amount from a resource. Returns whether the full amount was able to be consumes.Does not modify the resource if unable to consume the full amount.

bool status.overConsumeResource(String resourceName, float amount)

Tries to consume the specified amount from a resource. If unable to consume the full amount, will consume all theremaining amount. Returns whether it was able to consume any at all of the resource.

bool status.resourceLocked(String resourceName)

Returns whether the resource is currently locked.

void status.setResourceLocked(String resourceName, bool locked)

Sets a resource to be locked/unlocked. A locked resource cannot be consumed.

void status.resetResource(String resourceName)

Resets a resource to its base value.



void status.resetAllResources()

Resets all resources to their base values.

float status.resourceMax(String resourceName)

Returns the max value for the specified resource.

float status.resourcePercentage(String resourceName)

Returns the percentage of max that the resource is currently at. From 0.0 to 1.0.

void status.setResourcePercentage(String resourceName, float value)

Sets a resource to a percentage of the max value for the resource. From 0.0 to 1.0.

void status.modifyResourcePercentage(String resourceName, float value)

Adds a percentage of the max resource value to the current value of the resource.

JsonArray status.getPersistentEffects(String effectCategory)

Returns a list of the currently active persistent effects in the specified effect category.

void status.addPersistentEffect(String effectCategory, Json effect)

Adds a status effect to the specified effect category.

void status.addPersistentEffects(String effectCategory, JsonArray effects)

Adds a list of effects to the specified effect category.

2.36. status 35


void status.setPersistentEffects(String effectCategory, JsonArray effects)

Sets the list of effects of the specified effect category. Replaces the current list active effects.

void status.clearPersistentEffects(String effectCategory)

Clears any status effects from the specified effect category.

void status.clearAllPersistentEffects()

Clears all persistent status effects from all effect categories.

void status.addEphemeralEffect(String effectName, [float duration], [EntityIdsourceEntity])

Adds the specified unique status effect. Optionally with a custom duration, and optionally with a source entity idaccessible in the status effect.

void status.addEphemeralEffects(JsonArray effects, [EntityId sourceEntity])

Adds a list of unique status effects. Optionally with a source entity id.

Unique status effects can be specified either as a string, “myuniqueeffect”, or as a table, {effect = “myuniqueeffect”,duration = 5}. Remember that this function takes a list of these effect descriptors. This is a valid list of effects: {“myuniqueeffect”, {effect = “myothereffect”, duration = 5} }

void status.removeEphemeralEffect(String effectName)

Removes the specified unique status effect.

void status.clearEphemeralEffects()

Clears all ephemeral status effects.



List, uint64_t status.damageTakenSince([uint64_tsince = 0]])

Returns two values: * A list of damage notifications for the entity’s damage taken since the specified heartbeat. * Themost recent heartbeat to be passed into the function again to get the damage notifications taken since this function call.

Example:

_,lastStep = status.damageTakenSince() -- Returns the full buffer of damage→˓notifications, throw this away, we only want the current step

-- stuff

notifications,lastStep = status.damageTakenSince(lastStep) -- Get the damage→˓notifications since the last call, and update the heartbeat

List, uint64_t sta-tus.inflictedHitsSince([uint64_t since = 0]])

Returns two values: * A list {{entityId, damageRequest}} for the entity’s inflicted hits since the specified heartbeat. *The most recent heartbeat to be passed into the function again to get the inflicted hits since this function call.

List, uint65_t status.functionName([uint64_t since =0])

Returns two values: * A list of damage notifications for damage inflicted by the entity. * The most recent heartbeat tobe passed into the function again to get the list of damage notifications since the last call.

The world table contains functions that perform actions within a specified such as querying or modifying entities,tiles, etc. in that world.

float world.magnitude(Vec2F position1, Vec2F position2)

Returns the magnitude of the distance between the specified world positions. Use this rather than simple vectorsubtraction 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 tohandle world wrapping.

2.37. float world.magnitude(Vec2F position1, Vec2F position2) 37


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 world.nearestTo(Variant sourcePosition, Variant targetPo-sition)

Returns the point nearest to (i.e. on the same side of the world as) the source point. Either argument can be specifiedas a Vec2F point or as a float X position. The type of the targetPosition determines the return type.

bool world.pointCollision(Vec2F point, [CollisionSet colli-sionKinds])

Returns true if the generated collision geometry at the specified point matches any of the specified collision kindsand false otherwise.

bool world.pointTileCollision(Vec2F point, [CollisionSet colli-sionKinds])

Returns true if the tile at the specified point matches any of the specified collision kinds and false otherwise.



bool world.lineCollision(Vec2F startPoint, Vec2F endPoint,[CollisionSet collisionKinds])

Returns true if the line between the specified points overlaps any generated collision geometry of the specifiedcollision kinds and false otherwise.

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 falseotherwise.

bool world.rectCollision(RectF rect, [CollisionSet colli-sionKinds])

Returns true if the specified rectangle overlaps any generated collision geometry of the specified collision kinds andfalse otherwise.

bool world.rectTileCollision(RectF rect, [CollisionSet colli-sionKinds])

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 andfalse otherwise. If a position is specified, the polygon coordinates will be treated as relative to that world position.

List world.collisionBlocksAlongLine(Vec2F startPoint,Vec2F endPoint, [CollisionSet collisionKinds], [int maxRe-turnCount])

Returns an ordered list of tile positions along the line between the specified points that match any of the specifiedcollision kinds. If maxReturnCount is specified, the function will only return up to that number of points.

2.45. bool world.lineCollision(Vec2F startPoint, Vec2F endPoint, [CollisionSet collisionKinds])39


List world.liquidAlongLine(Vec2FstartPoint, Vec2F endPoint)

Returns a list of pairs containing a position and a LiquidLevel for all tiles along the line between the specifiedpoints that contain any liquid.

Vec2F world.resolvePolyCollision(PolyF poly, Vec2F position, floatmaximumCorrection, [CollisionSet collisionKinds])

Attempts to move the specified poly (relative to the specified position) such that it does not collide with any of thespecified collision kinds. Will only move the poly up to the distance specified by maximumCorrection. Returns nilif the collision resolution fails.

bool world.tileIsOccupied(Vec2I tilePosition, [bool foreground-Layer], [bool includeEphemeral])

Returns true if the specified tile position is occupied by a material or tile entity and false if it is empty. The checkwill be performed on the foreground tile layer if foregroundLayer is true (or unspecified) and the background tilelayer if it is false. The check will include ephemeral tile entities such as preview objects if includeEphemeral istrue, 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 directionis 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])

Attempts to spawn the specified item into the world as the specified position. If item is specified as a name, it willoptionally apply the specified count and parameters. Returns an EntityId of the item drop if successful and nilotherwise.



List world.spawnTreasure(Vec2F position, StringpoolName, float level, [unsigned seed])

Attempts to spawn all items in an instance of the specified treasure pool with the specified level and seed at thespecified world position. Returns a list of EntityIds of the item drops created if successful and nil otherwise.

EntityId world.spawnMonster(String monsterType, Vec2F posi-tion, [Json parameters])

Attempts to spawn a monster of the specified type at the specified position. If parameters are specified they will beapplied to the spawned monster. If they are unspecified, they default to an object setting aggressive to be randomlytrue or false. Level for the monster may be specified in parameters. Returns the EntityId of the spawnedmonster if successful and nil otherwise.

EntityId world.spawnNpc(Vec2F position, String npcType,String species, float level, [unsigned seed], [Json pa-rameters])

Attempts to spawn an NPC of the specified type, species, level with the specified seed and parameters at the specifiedposition. 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 po-sition, [EntityId sourceEntityId], [Vec2F direction], [booltrackSourceEntity], [Json parameters])

Attempts to spawn a projectile of the specified type at the specified position with the specified source entity id, direc-tion, and parameters. If trackSourceEntity is true then the projectile’s position will be locked relative to its sourceentity’s position. Returns the EntityId of the spawned projectile if successful and nil otherwise.

2.56. List world.spawnTreasure(Vec2F position, String poolName, float level,[unsigned seed])

41


EntityIdworld.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.

double world.time()

Returns the absolute time of the current world.

unsigned world.day()

Return the absolute numerical day of the current world.

double world.timeOfDay()

Return 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 total 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 bealtered by dungeons.

bool world.spawnLiquid(Vec2F position, LiquidId liquid, floatquantity)

Attempts to place the specified quantity of the specified liquid at the specified position. Returns true if successfuland false otherwise.

LiquidLevel world.destroyLiquid(Vec2F position)

Removes any liquid at the specified position and returns the LiquidLevel containing the type and quantity of liquidremoved, 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 startPo-sition, Vec2F endPosition, ActorMovementParameters move-mentParameters, PlatformerAStar::Parameters searchPa-rameters)

Attempts to synchronously pathfind between the specified positions using the specified movement and pathfindingparameters. Returns the path as a list of nodes as successful, or nil if no path is found.

2.68. LiquidLevel world.liquidAt(Vec2I position) 43


PlatformerAStar::PathFinder world.platformerPathStart(Vec2FstartPosition, Vec2F endPosition, ActorMovementParametersmovementParameters, PlatformerAStar::ParameterssearchParameters)

Creates and returns a Lua UserData value which can be used for pathfinding over multiple frames. The PathFinderreturned 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 isstill incomplete. If nodeLimit is unspecified, this will search up to the configured maximum number of nodes, makingit 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 beused 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.

bool world.underground(Vec2F position)

Returns true if the specified position is below the world’s surface level and false otherwise.



Variant world.material(Vec2F position, StringlayerName)

Returns the name of the material at the specified position and layer. Layer can be specified as ‘foreground’ or ‘back-ground’. Returns false if the space is empty in that layer. Returns nil if the material is NullMaterial (e.g. if theposition 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.

bool world.damageTiles(List positions, String layer-Name, Vec2F sourcePosition, String damageType, float dam-ageAmount, [unsigned harvestLevel])

Damages all tiles in the specified layer and positions by the specified amount. The source position of the damagedetermines the initial direction of the damage particles. Damage types are: “plantish”, “blockish”, “beamish”, “ex-plosive”, “fire”, “tilling”. Harvest level determines whether destroyed materials or mods will drop as items. Returnstrue if any damage was done and false otherwise.

bool world.damageTileArea(Vec2F center, float radius, String lay-erName, Vec2F sourcePosition, String damageType, floatdamageAmount, [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 canbe placed in a space occupied by mobile entities, otherwise such placement attempts will fail. Returns true if theplacement succeeds and false otherwise.

2.80. Variant world.material(Vec2F position, String layerName) 45


bool world.placeMod(Vec2I position, String layerName, StringmodName, [int hueShift], [bool allowOverlap])

Attempts to place the specified mod in the specified position and layer. If allowOverlap is true the mod can be placedin a space occupied by mobile entities, otherwise such placement attempts will fail. Returns true if the placementsucceeds and false otherwise.

List world.entityQuery(Vec2F position,Variant


List world.objectQuery(Vec2F position,Variant


List world.npcLineQuery(Vec2F startPosition, Vec2FendPosition, [Json options])

Identical to world.entityLineQuery but only considers NPCs.

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’texist.

bool world.entityCanDamage(EntityId sourceId, EntityId tar-getId)

Returns true if the specified source entity can damage the specified target entity using their current damage teamsand 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

starbound documentation - media.readthedocs.org · what is starbound 3. 2 actor mcontroller rectf...

Documents