Modding:JSON/Variables/Projectiles

From Starbounder - Starbound Wiki
Jump to: navigation, search
Mining Hazard Sign.png
Work In Progress!
Mining Hazard Sign.png

This article or section is currently in the process of an expansion or major restructuring.
You are welcome to assist in its construction by editing it as well.

Last edited by Photoloss on 2018-08-11 18:53:27.

These variables are defined in a projectiles's JSON file, found in the assets/projectiles folder. (Cannot locate, please update for current Starbound version: "Default parameters are defined in defaultparameters.config.")

Universal Parameters

This table is a list of parameters available to all projectiles without additional scripts. Modders can add parameters to a projectile's file, but be aware that overwriting one of these parameters may cause problems.

Parameter Name Variable Type Description
projectileName string The internal name of the projectile, as called by other json files.
image string The png used for the projectile.
processing directive A string of image processing directives, applied equally to all animation frames. An invalid directive will remove the image but the projectile will otherwise remain functional.
renderLayer string Assigns a render priority from a predefined list.
animationCycle float+ How fast the image animates, appears to be in seconds per frame.
timeToLive float If set this is how long before the projectile reaps.
frameNumber int+ Number of frames in the animation.
windupFrames int+ Number of frames in the animation for its windup before looping.
winddownFrames int+ Number of frames in the animation reserved for reaping if the main animation loops.
fullbright bool If true the projectile will always render at full brightness.
emitters string array The effectsources used for emission, defined in /effects.
pointLight bool If true the projectile will emit light from its origin point.
lightColor color RGB color definition for the point light. No alpha channel.
power float0+ Damage dealt by the projectile. Overwritten by most projectile creation actions.
speed float0+ Velocity in pixel coordinates per tick.
acceleration float Acceleration in "speed" per second. Always acts in current direction of travel.
orientationLocked bool If true the projectile won't rotate.
physics string Physics configuration key for lookup in /projectiles/physics.config file.
movementSettings projectilePhysics Direct JSON config for physics settings normally defined by the "physics" keyword. This includes the terrain collision hitbox, which may be different from the damagePoly.
bounces int The number of times a projectile can hit terrain or solid objects without being destroyed. If bounces is set to -1, the projectile will never be destroyed on contact with solids.
piercing bool If true the projectile won't reap on collision with enemies.
flippable bool If true the projectile can be flipped horizontally.
knockback int0+ The knockback the projectile inflicts on entities it hits.
knockbackDirectional bool If true, the projectile's knockback is applied in the direction the projectile was going at the time of collision. (?)
damageTeam damageTeam The damage team, accepts incomplete config override. Defines team membership of the projectile itself not the team to deal damage to.
damagePoly polyF The 'hitbox' polygon for entity collision, units appear to be pixels (1/8th of a block).
damageKind string The damage source kind to inflict. Damage sources are defined in /damage.
damageType damageType The damage type.
damageRepeatGroup string A seemingly arbitrary string tag to coordinate multi-hit limitations. If not specified this seems to be unique for each projectile instance.
damageRepeatTimeout float+ Time in seconds until members of this damageRepeatGroup may inflict damage on the same entity again.
statusEffects string/object mixed array The status effects the projectile inflicts. Input may be a name string or an object {"effect":"<name>", "duration":float}. Given a native definition and a config the entry with a higher duration takes precedence.
persistentStatusEffects string array Only observed on staff zones but not referenced in their scripts. Not affected by configs. Might accept duration format used in statusEffects.
statusEffectArea polyF The 'hitbox' polygon for persistent status application in blocks (8 pixels).
actionOnReap json These actions are ran when the projectile is destroyed under (almost?) any circumstance.
actionOnCollide json These actions are ran whenever the projectile collides with terrain or solid objects.
actionOnHit json These actions are ran whenever the projectile hits an entity. Does not work if "piercing":true, unknown if reap of projectile is necessary.
actionOnTimeout json These actions are ran when the projectile is reaped by expiration of its timeToLive or calls its die() function (boomerang return, staff dismissal etc.)
periodicActions json These actions are ran periodically. Requires a "time":float keyword and "repeat":bool in each action definition unlike similar arrays.
onlyHitTerrain bool If true the projectile will ignore entity collision entirely regardless of other settings. Custom lua scripts may still interact with nearby entities.
scripts string array Additional lua scripts to run in the projectile scope.
scriptDelta int or float Modifies the update rate of locally run lua scripts.
persistentAudio string Path to an audio file which is played continuously as long as the projectile exists.
boundBox rectF Bounding box for certain effects, most likely physicsForces.
physicsForces json Complex force applicator definition to apply to nearby entities. Does not obey Newton's laws. Does not accept custom configs.
clientEntityMode string Unknown, used in conjunction with physicsForces so may be necessary to prevent desyncs. Common value in this case is "ClientSlaveOnly".

Boomerang Projectiles

These projectiles attempt to track their creator entity and eventually return to it in some form. Most require communication with a compatible item script to identify the creator, if fired from a different source most features of these script will not function and the projectile will act almost like one without additional scripting. The first instance of such an unsupported projectile launch might freeze the game for an extended period of time, after which it will resume normal function and all subsequent launches should not cause further freezes.

Base Boomerang Projectile

Sourced from /scripts/projectiles/boomerangprojectile.lua. All other boomerang scripts (all three of them) attach to this one and require it active on the same projectile.

Parameter Name Variable Type Description
returning bool Whether the projectile is returning.
returnOnHit bool Whether the projectile will return on hit.
controlForce float Controls how quickly the projectile returns outside the snapping distance or slows down while it's not returning yet.
pickupDistance float Distance from the player at which the projectile disappears.
snapDistance float Distance from the player at which the projectile accelerates using controlForce. Inside that radius, it uses hardcoded acceleration of 500.
ignoreTerrain bool Whether the projectile has a terrain collision box. If true overrides movementSettings.collisionEnabled.
minVelocity float If current velocity is smaller than this, the projectile starts returning.

Lunarang

Sourced from /projectiles/activeitems/boomerang/lunarangprojectile.lua. Makes the boomerang projectile split on hit. Offers no config handle for shard projectiles.

Parameter Name Variable Type Description
shardCount int How many extra projectiles are spawned.
shardType string Projectile ID to be spawned on hit.

Wormerang

Sourced from /projectiles/activeitems/boomerang/wormerangprojectile.lua. Makes the boomerang projectile move in a sine wave.

Parameter Name Variable Type Description
wobbleRate float Wavelength
wobbleIntensity float Amplitude

Basic Chakram Projectile

Sourced from /projectiles/activeitems/chakram/chakramprojectile.lua. Uses a simplified version of the boomerang script.

Parameter Name Variable Type Description
returning bool Whether the projectile is returning.
returnOnHit bool Whether the projectile will return on hit.
pickupDistance float Distance from the player at which the projectile disappears.
maxDistance float If current distance from player is bigger than this, the projectile starts returning.
stickTime float For how long a sticky projectile will stick in terrain before returning.

Hover Chakram

Sourced from /projectiles/activeitems/chakram/hoverchakramprojectile.lua. Uses a somewhat different version of the base chakram script.

Parameter Name Variable Type Description
returning bool Whether the projectile is returning.
returnOnHit bool Whether the projectile will return on hit.
pickupDistance float Distance from the player at which the projectile disappears.
hoverMaxDistance float Maximum distance at which the projectile will fly from the player.
hoverTime float For how long a projectile will hover before returning.
ownerAimPosition vec2F The position the projectile will try to get to (if it's within range). Set with the player's aim position at the time of firing. World position.

Tentacle Fist

Sourced from /projectiles/guns/tentaclefist/tentaclefist.lua. Acts as an extension of the default boomerang script but requires communication with a tentaclegun script to make full use of all control features. The creator-tracking return portion remains fully functional even if not launched by a boomerang or tentaclegun ability.

Parameter Name Variable Type Description
targetTrackingForce float Control force for tracking the cursor or ability target.

Staff Projectiles

Some of the basic cursor tracking controls in these scripts are shared between multiple staff abilities and continue to function even if used with a different ability. Others, especially the defining features of Unique item abilities, only function to their full extent in combination with that specific ability script.

Basic Controlled Projectile

Sourced from /projectiles/activeitems/staff/staffprojectile.lua. In order to be effective some of these settings may require an active staff ability as the source of the projectile.

Parameter Name Variable Type Description
controlMovement dict Configuration of active cursor control. If outside a valid staff ability scope the creation point of the projectile acts as the homing focus instead. The following parameters are the only relevant entries:
controlMovement.maxSpeed float+ Maximum speed for controlled movement. Does not override speedLimit in projectile physics config.
controlMovement.controlForce float+ Force applied to control movement. Affected by mass. Negative values not reliable.
controlMovement.friction float0+ Friction applied to rotation of the projectile when tracking the cursor.
timedActions json A more elaborate form of periodic actions. Each action must have a loopTime to function and may optionally provide a delayTime and loopTimeVariance.

Ball Lightning

Sourced from /projectiles/activeitems/staff/balllightning/balllightning.lua. In order to be effective some of these settings may require an active staff ability as the source of the projectile. Does not inherit from the basic staffprojectile.lua and may in fact conflict with it. This script implements the unique "jerky" movement of the Tesla's Staff secondary ability.

Parameter Name Variable Type Description
waitTime float+ Idle time between movement periods.
moveTime float+ Duration of movement period.

Bouncer

Sourced from /projectiles/activeitems/staff/elementbouncer/bouncespikes.lua. In order to be effective some of these settings may require an active staff ability as the source of the projectile. Does not inherit from the basic staffprojectile.lua but is intended to run in parallel with it. There is no provision for custom configs on the spike projectile.

Parameter Name Variable Type Description
spikeProjectile string Projectile ID to be spawned as spikes on terrain impact.
spikeDamageFactor float0+ Multiplier for spike damage relative to the parent projectile.
checkDistance float0+ Maximum distance up to which terrain collision is evaluated to place spikes.
checkDirections int+ A full circle is evenly divided by this many rays to define the search directions for spike placement.
maxSpikes int+ Maximum number of spikes produced PER BOUNCE. This script provides no limitation on the maximum total number of spikes generated.

Portal

Sourced from /projectiles/activeitems/staff/elementportal/elementportal.lua. In order to be effective some of these settings may require an active staff ability as the source of the projectile. Does not inherit from the basic staffprojectile.lua and the two may conflict. This script allows secondary projectiles to be linked to the ability scope allowing them to be controlled by the caster.

Parameter Name Variable Type Description
projectileType string Projectile ID to be spawned periodically.
projectileParameters json Full projectile config for the spawned secondary projectiles. The power and powerMultiplier parameters are overwritten.
spawnRate float+ Time in seconds between projectile spawns.

Kluex Staff

Sourced from /projectiles/activeitems/staff/kluexstaffplasma/kluexstaffplasma.lua. In order to be effective some of these settings may require an active "kluexshooter" ability as the source of the projectile. Does not inherit from the basic staffprojectile.lua and the two may conflict. The kluexshooter.lua ability script is required to properly trigger the secondary attack from this projectile. The "energycrystal" projectile attack is hardcoded and cannot be customized. These scripts operate the Kluex Staff primary ability.

Parameter Name Variable Type Description
controlRotation dict JSON object detailing cursor-tracking rotation. Only the following entries are used:
controlRotation.maxSpeed float0+ Maximum rotation speed. Units unknown.
controlRotation.controlForce float0+ Acceleration of cursor-tracking rotation. Units are "speed per game tick".
controlRotation.friction float0+ Dampening of the rotation proportional to current speed. Units of "per game tick".
explosionAction json Action array to be executed when the secondary attack is triggered. Independent of the actual projectile attack.

Plasma Ball

Sourced from /projectiles/activeitems/staff/plasmaball/plasmaball.lua. In order to be effective some of these settings may require an active "plasmabarrage" type ability as the source of the projectile. Does not inherit from the basic staffprojectile.lua and the two may conflict. This script operates the Ferozium Wand primary ability.

Parameter Name Variable Type Description
delayTime float Time delay in seconds until the delayed launch. Dynamically overwritten by the plasmabarrage.lua script but may be set manually in a different context.
triggerSpeed float0+ Speed of delayed launch. Acceleration is instantaneous and the direction may be controlled by compatible abilities.

Plasma Blade

Sourced from /projectiles/activeitems/staff/plasmablade/plasmablade.lua. In order to be effective some of these settings may require an active "plasmabarrage" type ability as the source of the projectile. Does not inherit from the basic staffprojectile.lua and the two may conflict. This script operates the Ferozium Staff primary ability.

Parameter Name Variable Type Description
delayTime float Time delay in seconds until the delayed launch. Dynamically overwritten by the plasmabarrage.lua script but may be set manually in a different context.
triggerSpeed float0+ Speed of delayed launch. Acceleration is instantaneous and the direction may be controlled by compatible abilities.
controlRotation dict JSON object detailing cursor-tracking rotation, same as Kluex Shooter above. Only the following entries are used:
controlRotation.maxSpeed float0+ Maximum rotation speed. Units unknown.
controlRotation.controlForce float0+ Acceleration of cursor-tracking rotation. Units are "speed per game tick".
controlRotation.friction float0+ Dampening of the rotation proportional to current speed. Units of "per game tick".

Staff Projectile Spawner

Sourced from /projectiles/activeitems/staff/staffprojectilespawner.lua. In order to be effective some of these settings may require an active staff ability as the source of the projectile. Does not inherit from the basic staffprojectile.lua and the two may conflict. This script is not connected to the portal ability in any way and appears to be unused, providing a single delayed spawn rather than continuous production of secondary projectiles.

Parameter Name Variable Type Description
spawnDelay float0+ Time in seconds until the delayed secondary projectile spawn.
spawnProjectile string Projectile ID to be spawned after the delay.
spawnParams json Full projectile config for the spawned secondary projectile. The power and powerMultiplier parameters are overwritten.

Homing and Guidance

Autonomous homing missiles and projectiles guided by the source ability.

Homing Rocket

Sourced from /projectiles/guns/rockets/homingrocket/homingrocket.lua. Handles homing secondary ability for rocket launchers. Relies on input from the source ability to obtain a valid target entity.

Parameter Name Variable Type Description
controlForce float Force to direct the homing movement.
maxSpeed float Maximum speed the homing system can achieve.

Rocket Burst

Sourced from /projectiles/guns/rockets/minirocket/minirocket.lua. Handles the Rocket Burst secondary ability for rocket launchers. Script appears identical to miniknogrocket but the source ability uses its setApproach() function to redirect the rocket along the player aim direction.

Parameter Name Variable Type Description
controlForce float Force to direct acceleration.
maxSpeed float Maximum speed this scripted acceleration can achieve.

Guided Rocket

Sourced from /projectiles/activeitems/guidedrocket/guidedrocket.lua. Handles guided secondary abilities for rocket launchers. Relies on communication with the source ability and is not compatible with staff guidance mechanics.

Parameter Name Variable Type Description
trailProjectile string Projectile ID created at fixed intervals as this projectile moves. Does not support custom JSON configs for secondary projectiles.
trailDistance float Distance interval (likely in blocks = 8 pixels) in which trailProjectile spawns occur. Purely distance-based, no new spawns will occur if the guided rocket moves in a tight circle.
maxTrackingAngle float Maximum angle (in degrees) the missile can attempt to turn relative to its current direction of travel.
rotationRate float Rate at which the projectile can turn to track its target, likely in "degrees per tick".

Marked Shot - Chain Bullet

Sourced from /scripts/projectiles/chainbullet.lua. Implements a manual-selection "chain lightning" type attack for the Sniper Rifle's Marked Shot ability. Targets must be set externally as a list of entityId entries. Iteratively seeks out the closest target from the previous impact position. Does not accept custom JSON for the chainProjectile.

Parameter Name Variable Type Description
seekSpeed float Fixed speed at which targets are approached.
triggered bool State tracking variable, avoid manual modification.
targets entityId array List of targets to seek out. Can be set manually but requires knowledge of their entityId values.
chainProjectile string Projectile ID to be launched as a secondary chain component.

Fuel Air Coud

Sourced from /projectiles/activeitems/fuelaircloud/fuelaircloud.lua. Handles the Flamethrower secondary ability and relies on it for ignition functionality.

Parameter Name Variable Type Description
chainProjectile entityId This projectile is sent an "ignite" call when the current projectile is ignited.
igniteAction json Projectile action triggered when this projectile is sent an "ignite" call.
cutoffTime float If the projectile's remaining time to live is smaller than this value any incoming "ignite" calls are ignored.
chainTime float Delay time between processing this projectile's igniteAction and sending its own "ignite" call to the chainProjectile.

Grappling Hook

Sourced from /projectiles/activeitems/grapplehook/grapplehook.lua. Mainly necessary for communicating back to the Rope or Grappling Hook source item. One parameter is completely independent though:

Parameter Name Variable Type Description
breakOnSlipperyCollision bool If true the projectile is destroyed when detected to be sliding across a surface instead of coming to a full stop with the first impact.

Translocator Disc

Sourced from /projectiles/activeitems/translocatordisc/translocatordisc.lua. Handles positioning for the teleport action of the Translocator.

Parameter Name Variable Type Description
teleportOffset vec2F Offset from the projectile location which is chosen as the teleport target.
teleportTolerance float Range within a valid placement location can be searched for.

Mech Weapons

Projectiles used by Mechs. These may require external triggers from mech scripts.

Cluster Mine

Sourced from /scripts/projectiles/remotedetonatedprojectile.lua. Requires an external "triggerRemoteDetonation" message to trigger on demand, but this only forces a normal timeout reap. The actual detonation is handled via actionOnReap and thus eventually occurs even if no trigger is given.

Parameter Name Variable Type Description
triggerDelayRange range Minimum and maximum time between receiving the detonate message and actual timeout.

Energy Pickup

Sourced from /projectiles/mech/mechenergypickup/mechenergypickup.lua. Automatically seeks nearby "modularmech" vehicles and sends a "restoreEnergy" message upon successful pickup.

Parameter Name Variable Type Description
pickupRange float Range in blocks (=8 pixels) within which the projectile will send its restore message and reap.
snapRange float Seeking range in blocks (=8 pixels) for acquiring mech targets.
snapSpeed float Maximum speed the pickup homing system can achieve.
snapForce float Acceleration force for homing pickup.
restoreBase float Flat amount of energy to restore.
restorePercentage float Percentage of target mech energy to restore.

Homing Missile

Sourced from /scripts/projectiles/homingprojectile.lua. Fully autonomous homing missile with intelligent target filtering. Requires a valid source entity and will only acquire targets which this source can damage.

Parameter Name Variable Type Description
homingDistance float Range for target acquisition centered on the missile. The list of targets is updated continuously.
rotationRate float Rotation rate for course correction, seemingly in "degrees per game tick".
trackingLimit float Angular tracking limit relative to current direction of travel, seemingly in radians.
timeToLiveVariance float Variance for random addition to the base timeToLive, possibly from a Gaussian distribution as opposed to standard uniform ranges.

Guided Missile

Sourced from /scripts/projectiles/guidedprojectile.lua. Homes in on a given target position which may be statically defined or constantly updated via a "setTargetPosition" message. Not compatible with rocket launcher or staff guidance abilities.

Parameter Name Variable Type Description
targetPosition vec2F Position the missile is guided to.
rotationRate float Rotation rate for course correction, seemingly in "degrees per game tick".
trackingLimit float Angular tracking limit relative to current direction of travel, seemingly in radians.
timeToLiveVariance float Variance for random addition to the base timeToLive, possibly from a Gaussian distribution as opposed to standard uniform ranges.

Fancy Movement

Projectiles with complex movement patterns but no reliance on input from their source.

Delaybullet

Sourced from /projectiles/activeitems/delaybullet/delaybullet.lua. A standalone script which updates the projectile's speed after a given delay. May fail if the projectile has a speed of 0 at the time of triggering.

Parameter Name Variable Type Description
delayTime float0+ Time in seconds until the delayed speed reset.
triggerSpeed float New velocity after trigger.

Miniknog Rocket

Sourced from /projectiles/activeitems/miniknogrocket/miniknogrocket.lua. Seemingly implements a basic linear acceleration which should be possible with universal parameters. Has a setApproach() function which remains unused but is compatible with the Rocket Burst rocket launcher ability.

Parameter Name Variable Type Description
maxSpeed float Maximum speed to accelerate to.
controlForce float Force to drive acceleration.

Sine Wave

Sourced from /scripts/projectiles/sinewaveprojectile.lua. Makes the projectile move in a sine wave pattern. The overall direction of travel remains unchanged. Has no phase offset parameter. Relies on iterative construction so other scripts which change the projectile's facing will destroy the sine wave pattern. The wave is mirrored if the projectile is fired in negative world Y direction. Has a built-in phase offset and actually starts in the minimum of the wave, mathematically defined as -cos(x). This also means the time-average line of travel is offset from the launch point by a full amplitude.

Parameter Name Variable Type Description
wavePeriod float Time period (in seconds) for a full 2pi oscillation of the sine wave. A negative value mirrors the entire wave across the launch direction yielding +cos(x).
waveAmplitude float Amplitude (zero line to peak, in blocks = 8 pixels) of the sine wave. A negative value mirrors the entire wave across the launch direction yielding +cos(x).

Zigzag

Sourced from /scripts/projectiles/zigzagprojectile.lua. Makes the projectile move in a zigzag pattern. Appears to be unused as of version 1.3.

Parameter Name Variable Type Description
zigZagTime float Time period (in seconds) between each change of direction.
zigZagAngle float Angle (in degrees?) which the projectile is rotated back and forth.

Monster Attacks

These projectiles generally require communication with a monster script in order to function. Some aspects may work even without a valid creator script but extra care should be given as lack of input may cause crashes.

Ape Boss Missile

Sourced from /projectiles/boss/apeboss/apebossmissile/apebossmissile.lua. A homing missile directed at a specific entity. The target entity must be set via an external lua call which is not compatible with similar weapon abilities.

Parameter Name Variable Type Description
controlForce float Force controlling homing.
maxSpeed float Maximum speed the homing behavior can accelerate to.

Space Monster Spawner

Sourced from /projectiles/boss/eyeboss/spacemonsterspawner.lua. Used to spawn monsters and communicate the spawns back to the boss monster. The basic spawning functionality still works even without a valid source entity but the first spawn attempt without one will cause the game to freeze for a lengthy period of time. After the freeze concludes successive uses should function without further freezing. In general it is recommended to use actionOnReap with a "spawnmonster" action instead of this special projectile.

Parameter Name Variable Type Description
monsterType string Monster ID to be spawned.
monsterLevel int Supposedly a monster level from 0 to 10, but the parameter is overwritten immediately and thus remains effective unused.
monsterParameters json JSON config for the monster to be spawned. Some parameters are given presets by the script.

Delayed Plasma Shot

Sourced from /projectiles/boss/guardianboss/delayedplasmashot.lua. Automatically acquires a random player within 200 range as its target. Upon timing out launches a hardcoded plasmashot projectile and processes its explosionAction.

Parameter Name Variable Type Description
explosionAction json Action to be processed when the projectile times out while having a valid tracking target.

Delayed Plasma Ball

Sourced from /projectiles/boss/kluexboss/delayedplasma/delayedplasmaball.lua. Does not automatically acquire a target, instead relies on an external message. Upon timing out launches a hardcoded energycrystal projectile and processes its explosionAction.

Parameter Name Variable Type Description
explosionAction json Action to be processed when the projectile times out while having a valid source entity.

Ice Eruption

Sourced from /projectiles/boss/kluexboss/iceeruption/iceeruptiontele.lua. Processes its eruptionAction upon timing out.

Parameter Name Variable Type Description
eruptionAction json Action to be processed when the projectile times out while having a valid source entity.

Fishing

Sourced from /projectiles/activeitems/fishinglure/fishinglure.lua. Fishing mechanics are split between the rod item and the lure projectile. The rod does not support custom projectile JSON and the lure has limited functionality on its own, so be extra careful in attempting to modify these parameters without knowledge of the lua script.

Parameter Name Variable Type Description
lineOffset vec2F Offset position for attaching the fishing line, visual only.
reelParameters json Various parameters used by both the fishing rod item script and the spawned fish monsters. The projectile itself only uses one parameter:
reelParameters.reelSpeed float Speed at which the lure can be reeled in when commanded by the rod script.
lureParameters json Various parameters used to control the movement of the lure:
lureParameters.controlSpeed float Speed at which the lure can be moved while submerged.
lureParameters.controlForce float Force which drives the controlled movement.
spawnTimeRange randomRange Interval in seconds describing the minimum and maximum times between fish spawns.
scareFishRange float Fish within this range (in blocks?) are messaged to move away from the lure.
scareFishTime float Period time (in seconds) for messaging fish to move away from the lure.


Quick Navigation