Skip to content

Home

Jump to bottom
ChronoVortex edited this page Aug 3, 2024 · 41 revisions

This wiki outlines the new tags and LUA utility functions made available by Vertex.

Weapon and Drone Tags

mindControl

Can be used with weapon blueprints. Crew hit by the weapon will be mind controlled.

Value: Determines the duration of the mind control.

Attributes:

  • limit (optional) - If specified, limits the number of crew that can be mind controlled by each of the weapon's projectiles to the given value. In unspecified, an unlimited number of crew may be mind controlled. Does not work with beams.
  • endSound (optional) - If specified, this sound will play when mind control ends on crew effected by this weapon.

Example: A weapon with this tag will mind control up to 2 enemy crew for 10 seconds when it hits. When mind control on each crew member ends, the mindControlEnd sound effect will play.

<mindControl limit="2" endSound="mindControlEnd">10</mindControl>

augEffects and augEffect

Can be used with weapon or drone blueprints. Equipment with these tags will provide the specified augment effects. Any number of augEffect tags can be defined as children of augEffects. Attributes belong to augEffect.

Attributes:

  • effect - The augment effect the equipment should provide. Refer to Hyperspace documentation for available augments.
  • amount - The amount of the given effect that will be provided.
  • needsPower (optional) - If true, the equipment must be powered to provide this effect. Otherwise it will provide the effect while equipped. If not specified, will be true by default.
  • chargeScaling (optional) (weapon blueprints only) - If true, the amount will scale by the number of charges the weapon has. If not specified, will be false by default.
  • nostack (optional) - If true, this augment value will overwrite the existing augment value if it is greater. Otherwise it will be added to the existing augment value. If not specified, will be false by default.

Example: A weapon with these tags will always increase shield recharge speed by 50% while equipped, improve weapon cooldown by 20% while fully charged and set ammo replication chance to 30% if it isn't already higher while powered.

<augEffects>
    <augEffect effect="SHIELD_RECHARGE" amount="0.5" needsPower="false"/>
    <augEffect effect="AUTO_COOLDOWN" amount="0.2" chargeScaling="true"/>
    <augEffect effect="EXPLOSIVE_REPLICATOR" amount="0.3" nostack="true"/>
</augEffects>

Additional Notes: The following augment effects do not function correctly with these tags.

  • FTL_JUMPER_GOOD
  • O2_MASKS
  • SLUG_GEL
  • FIRE_EXTINGUISHERS

lockdownBeam

Can be used with beam weapon blueprints. Rooms hit by the beam will be locked down.

Attributes:

  • chance (optional) - If specified, each room the beam hits will have this chance to be locked down. If not specified, each room is guaranteed to be locked down.

Children:

  • sound (optional) - Will play this sound when a room is locked down. If no sounds are specified, no sound will play.

Example: A beam weapon with this tag will have a 70% chance to lock down rooms it hits, playing the sound lockdown1 or lockdown2 when it does.

<lockdownBeam chance="7">
    <sound>lockdown1</sound>
    <sound>lockdown2</sound>
</lockdownBeam>

hack

Can be used with weapon blueprints. Systems hit by the weapon will be hacked.

Attributes:

  • duration - How long the hack lasts.
  • hitShieldDuration (optional) - If defined, the shield system will be hacked for this long when the weapon hits the shield bubble.
  • immuneAfterHack (optional) - If defined, the hacked system will be immune to hacking weapons for this long after the hack is completed.
  • boostHackingTimeAddition (optional) - If defined, and if the weapon has a boost defined, the hack applied will be increased by this much time from the base duration for each level of boost.

Children:

  • shields, engines, oxygen, weapons, drones, medbay, pilot, sensors, doors, teleporter, cloaking, artillery, battery, clonebay, mind, hacking, temporal (optional) - Override the base hack duration for this system with the given value. Each system child tag can also have an immuneAfterHack attribute which overrides the base value.

Example: If a weapon with this tag hits the shield bubble, it will hack shields for 4 seconds. If it hits the engine system, it will hack it for 3 seconds. If it hits the door system, it will hack it for 10 seconds. Any other system it hits will be hacked for 7 seconds. Once the hack is completed, the affected system will be immune to being hacked by weapons with this tag for 2 seconds (4 for the weapons system).

<hack duration="7" hitShieldDuration="4" immuneAfterHack="2">
    <weapons immuneAfterHack="4">7</weapons>
    <engines>3</engines>
    <doors>10</doors>
</hack>

Example 2: If a weapon with these tags hits a system, it will hack it for 6 seconds on the first shot, 8 seconds on the second shot, 10 seconds on the third shot, etcetera.

<boost>
    <type>damage</type>
    <amount>0.01</amount>
    <count>5</count>
</boost>
<hack duration="6" boostHackingTimeAddition="2"/>

Additional Notes:

  • Weapons with this tag have no effect on systems with a hacking drone.
  • boostHackingTimeAddition only works correctly for boosts with a count greater than 1.

noPowerFix

Can be used with weapon blueprints. Weapons with <noPowerFix/> that use no power will fire correctly while no other weapons are powered.

preignited

Can be used with weapon blueprints. Weapons with <preignited/> will charge to full on jump without needing a weapon pre-igniter.

stealth

Can be used with non-beam weapon blueprints. Weapons with <stealth/> won't impact the cloak timer even if its ship has no Stealth Weapons.

particleEmitters

Can be used with weapon blueprints. Refer to the Particle System page for details.

Other Tags

shipBlueprint Tags

mapImage

Can be used to set a custom map icon for a ship.

Value: The name of the image to use for the icon. It should be in the img/map directory and have a second version with _fuel appended to the end of the name.

Attributes:

  • offset (optional) - If specified, the icon will be drawn this many pixels further away from the beacon.

Example: A ship with this tag will load its map icons from img/map/map_icon_myship.png and img/map/map_icon_myship_fuel.png. The icons will be drawn 5 pixels further away from the beacon than normal.

<mapImage offset="5">map_icon_myship</mapImage>

LUA Utility Functions

All utility functions belong to the mods.vertexutil table. To call them, use mods.vertexutil.function_name(args).

vter

Generic iterator for C vectors.

Parameters:

  • cvec - The vector to iterate over.

Return: An iterator for the vector.

Example: Printing the names of all player crew.

for crew in mods.vertexutil.vter(Hyperspace.ships.player.vCrewList) do
    print(crew:GetName())
end

table_copy_deep

Copies a LUA table and all nested data.

Parameters:

  • value - The table to be copied.

Return: Copy of value.

under_mind_system

Checks if a crew member is being mind controlled by a ship's mind control system (NOT if being mind controlled by a weapon).

Parameters:

  • crewmem - The crew member to check.

Return: true if being mind controlled by a system, false if not.

resists_mind_control

Checks if a crew member is resistant to mind control.

Parameters:

  • crewmem - The crew member to check.

Return: true if the crew member is resistant to mind control, false if not.

can_be_mind_controlled

Checks if a crew member is currently able to be mind controlled.

Parameters:

  • crewmem - The crew member to check.

Return: true if able to be mind controlled, false if not.

get_ship_crew_point

Gets a table of all crew currently occupying a room cell on a given ship. Only gets crew owned by the given ship.

Parameters:

  • shipManager - The ship to retrieve crew from.
  • x - X coordinate of the room cell to retrieve crew from.
  • y - Y coordinate of the room cell to retrieve crew from.
  • maxCount (optional) - The maximum number of crew to retrieve. Maximum is unlimited if unspecified.

Return: A table containing all retrieved crew.

get_adjacent_rooms

Gets a table of all rooms adjacent to the given room.

Parameters:

  • shipId - The ID of the ship to retrieve rooms from.
  • roomId - The ID of the given room.
  • diagonals (optional) - If true, rooms which are diagonally adjacent to the given room will also be retrieved. false by default.

Return: A table where the keys are the IDs of all rooms adjacent to the given room.

get_room_at_location

Finds the ID of the room at a given location.

Parameters:

  • shipManager - The ShipManager to search for the room.
  • location - The Pointf coordinates to search for the room.
  • includeWalls - If true, room walls will be included in the search. If false, walls will be excluded.

Return: The ID of the room found, or -1 if no room was found.

userdata_table

Gets a table of persistent data for a given userdata value.

Parameters:

  • userdata - A userdata value with a table member (can be a CrewMember, Projectile, ProjectileFactory, Room, ShipManager, ShipSystem or SpaceDrone).
  • tableName - A unique identifier for the table. Should be complex enough to be different from any other identifier in your mod and in other mods.

Return: The userdata table.

Example: Save an arbitrary data value to a player crew member and retrieve it.

local crewmem = Hyperspace.ships.player.vCrewList[0]
mods.vertexutil.userdata_table(crewmem, "mods.thisModName.exampleTable").arbitraryValue = 10
local retrivedValue = mods.vertexutil.userdata_table(crewmem, "mods.thisModName.exampleTable").arbitraryValue

is_first_shot

Check if a given weapon is currently on its first shot.

Parameters:

  • weapon - The ProjectileFactory to check.
  • afterFirstShot (optional) - Should be true if this function is being called after the weapon has fired its first shot. false by default.

Return: true if the weapon is on its first shot, false if not.

random_point_radius

Generate a random point within the radius of a given point.

Parameters:

  • origin - The Pointf coordinates from which to generate a random point.
  • radius - The area around origin that the point can be generated in.

Return: The random point generated as a Pointf.

ShowTutorialArrow

Show the tutorial arrow.

Parameters:

  • dir - The direction the arrow should point. Use 0 for right, 1 for down, 2 for left and 3 for up.
  • x - X coordinate to show the arrow at.
  • y - Y coordinate to show the arrow at.

Return: None.

HideTutorialArrow

Hide the tutorial arrow.

Parameters: None.

Return: None.

Clone this wiki locally