Tutorial Adding custom cursors/reticles to weapons

When I heard that weapon reticles were being added to Starbound, the very first thing that crossed my mind was "I want to add custom cursors to my own modded weapons!". Unfortunately, there didn't seem to be any variables in the weapon JSON files that could set a custom cursor, and I later figured out that the default cursor/reticle is actually set in the general gun.lua script, which acts as a base for all guns in the game.

If you know a bit of Lua, it's actually quite easy to adjust this script to allow for custom cursors without breaking any of the game's existing weapons (as far as I could test). Here's how:

Change this line in gun.lua (found in /items/active/weapons/ranged):

Code:

activeItem.setCursor("/cursors/reticle0.cursor")

to this:

Code:

self.cursor = item.instanceValue("cursor")
 
  if (self.cursor) then
    activeItem.setCursor(self.cursor)
  else
    activeItem.setCursor("/cursors/reticle0.cursor")
  end

This makes the gun script first check if a custom cursor was defined in your weapon's JSON file, then either set this custom cursor as the current cursor, or set it to the default one if no cursor was defined in the JSON file. In order to use this for custom cursors, just add a "cursor" variable to your weapon (.activeitem) and set its value to the path for your custom cursor. For example:

Code:

"cursor" : "/cursors/testreticle.cursor"

Feel free to use this in any of your mods, and have fun adding your own cursors and reticles!

And for those who just want the modded gun.lua, here's the full code:

Code:

require "/scripts/util.lua"
require "/scripts/vec2.lua"
require "/scripts/interp.lua"
require "/items/active/weapons/weapon.lua"
require "/items/active/weapons/ranged/gunfire.lua"

function init()
  self.cursor = item.instanceValue("cursor")
 
  if (self.cursor) then
    activeItem.setCursor(self.cursor)
  else
    activeItem.setCursor("/cursors/reticle0.cursor")
  end
 
  animator.setGlobalTag("paletteSwaps", item.instanceValue("paletteSwaps", ""))
 
  self.weapon = Weapon:new()

  self.weapon:addTransformationGroup("weapon", {0,0}, 0)
  self.weapon:addTransformationGroup("muzzle", self.weapon.muzzleOffset, 0)

  local primaryAttack = GunFire:new(item.instanceValue("primaryAttack"), item.instanceValue("stances"))
  self.weapon:addAbility(primaryAttack)

  local secondaryAttack = getAltAbility(self.weapon.elementalType)
  if secondaryAttack then
    self.weapon:addAbility(secondaryAttack)
  end
 
  self.weapon:init()
end

function update(dt, fireMode, shiftHeld)
  self.weapon:update(dt, fireMode, shiftHeld)
end

function uninit()
  self.weapon:uninit()
end

 

Interesting. What happens if multiple mods change the base gun.lua?

edit: Derp, that's what patch files are for. But still, what happens if multiple mods change the base gun.lua to the same thing?

edit 2: Why isn't this in the vanilla game?

 

Yeah, this is definitely a feature that would be nice as a vanilla feature - let's hope Chucklefish takes note! As for your other questions:

As far as I know, Lua files can't be patched - that's for JSON files. Any mod which would want to do this would have to overwrite the base gun.lua file. I haven't tested this yet,but I would imagine that as long as mods apply the exact same modifications to the gun.lua script, they should be compatible with each other. I would think that each mod overwrites the base gun.lua as it is loaded into the game, so whichever mod is loaded last will apply the final change to the gun.lua script - and as long as each mod applies the same change, it doesn't matter which mod is loaded last.

That being said, I think there is a way to make this more compatibility-friendly. Every weapon built using the .activeitem system has this line in it:

Code:

"scripts" : ["/items/active/weapons/ranged/gun.lua"],

If you'd duplicate the gun.lua script and rename it to whatever you fancy (for example, gun-custom.lua), and then add my changes to this duplicated gun.lua script, you could simply make the weapon use your custom gun script instead of the base gun.lua script and everything should work. Any weapons with custom cursors would then have to have a "cursor" variable in it, and change the above line of code to this:

Code:

"scripts" : ["/items/active/weapons/ranged/gun-custom.lua"],

 

Ah, thanks for clarification!