Lua:Tutorial GettingStarted

Development < Lua Scripting < Lua:Tutorial GettingStarted

Here are some examples of small widgets, with useful code to get you started!

To play with each example, place the code into a "my_new_widget_name.lua" file in your Spring/LuaUI/widgets dir (create it if not already present) and run Spring with any game. Your widget should then appear ingame!

To see many more examples, check out the LuaUI/widgets directory of the games in PublicRepos.

Note that every widget (and gadget) must include a GetInfo() callin, but all other callins are optional.

Example 1

The "hello world" example, with a ticking clock. <syntaxhighlight lang="lua"> function widget:GetInfo()

  return {
     name         = "Name as shown in widget list",
     desc         = "Description as normally shown in tooltip",
     author       = "It could be you!",
     date         = "now",
     license      = "PD", -- should be compatible with Spring
     layer        = 0,
     enabled      = true
  }

end

local helloWorld = "I STARTED LOOK AT ME JIM!" local toggle

function widget:Initialize()

  Spring.Echo(helloWorld)

end

function widget:Update()

  if (toggle == true) then
     Spring.Echo("TOCK")
     toggle = false
  else
     Spring.Echo("TICK")
     toggle = true
  end

end </syntaxhighlight>

Example 2

How to make stuff happen when units do stuff. <syntaxhighlight lang="lua"> function widget:GetInfo()

  return {
     name         = "Unit Announcer",
     desc         = "Units are proud to be alive",
     author       = "Some guy",
     date         = "I don't know why we include dates",
     license      = "GPLv2 or later",
     layer        = 0,
     enabled      = true
  }

end

local machoUnits = {}

function widget:UnitCreated(unitID, unitDefID, unitTeam, builderID)

 Spring.Echo("HELLO")

 local humanName = UnitDefs[unitDefID].humanName
 local numWeapons = #UnitDefs[unitDefID].weapons
 local plural = numWeapons~=1 and "s" or ""

 Spring.Echo("I am unit " .. unitID .. ". I am a " .. humanName .. ".")
 Spring.Echo("I have " .. numWeapons .. " weapon" .. plural .. ".")
 if numWeapons>0 then
   machoUnits[unitID] = true
 end

end

function widget:UnitDestroyed(unitID, unitDefID, unitTeam, attackerID, attackerDefID, attackerTeam)

 machoUnits[unitID] = nil

end

function widget:UnitDamaged(unitID, unitDefID, unitTeam, damage, paralyzer, weaponDefID, projectileID, attackerID, attackerDefID, attackerTeam)

 if machoUnits[unitID] then return end

 local n = math.random(3,10)
 local ow = "O"
 for i=1,n do
   ow = ow .. "W"
 end
 Spring.Echo(ow)

end </syntaxhighlight>

Example 3

Something actually useful. <syntaxhighlight lang="lua"> function widget:GetInfo()

 return {
   name      = "Stop means Stop",
   desc      = "Cancels Self D orders when unit is given a stop command",
   author    = "enotseulB",
   date      = "GPL v2 or later",
   license   = "Feb 2015",
   layer     = 0,
   enabled   = true  
 }

end

local CMD_STOP = CMD.STOP

function widget:UnitCommand(unitID, unitDefID, teamID, cmdID, cmdParams, cmdOptions)

   if cmdID ~= CMD_STOP then return end
   if not unitID then return end
   if teamID ~= Spring.GetMyTeamID() then return end

   if (Spring.GetUnitSelfDTime(unitID) > 0) then
       Spring.GiveOrderToUnit(unitID, CMD.SELFD, {}, {})
   end 

end </syntaxhighlight>