Lua Scripting tutorial - Return to the Roots mod for The Settlers II: Veni, Vidi, Vici

Functions to be called from Lua:

• rttr.AddWares(player, type, amount, ...)
  Add the specified goods to the player's first warehouse. 'type' and 'amount' may be repeated, but have to appear in pairs.
• rttr.AddPeople(player, type, amount, ...)
  Add the specified people to the player's first warehouse. 'type' and 'amount' may be repeated, but have to appear in pairs.
• rttr.EnableBuilding(player, type, ...)
  Enable the buildings specified after player. 'type' may be repeated to enable multiple buildings.
  With no type given, all buildings are enabled.
• rttr.DisableBuilding(player, type, ...)
  Disable the buildings specified after player. 'type' may be repeated to disable multiple buildings.
  With no type given, all buildings are disabled.
• rttr.SetRestrictedArea(player, x1,y1, ...)
  This restricts the area a player may have territory in. If called without any x/y-values, the restrictions are lifted. Otherwise, the coordinates specify one or multiple polygons the player may have territory in. A polygon inside a polygon will create a hole in it. To specify multiple polygons, start with a 0,0-pair followed by the first polygon, another 0,0-pair, the second polygon etc. and a final 0,0-pair at the end. For multiple polygons, each polygons first point has to be repeated at the end of it.
• rttr.GetGF()
  Returns the current game frame number.
• rttr.AddStaticObject(x, y, id, file = 0xFFFF, size = 0)
  Adds new static object. Only environment/static objects and empty space can be overwritten.
  id: id in file
  file: 0xFFFF map_?_z.lst, 0-5 mis?bobs.lst
  size: 0 for hut, 1 for house, 2 for castle.
  See Bazaar.launchpad.net
• rttr.AddEnvObject(x, y, id, file = 0xFFFF)
  Adds new environment object. Only environment/static objects and empty space can be overwritten.
  id: id in file
  file: 0xFFFF map_?_z.lst, 0-5 mis?bobs.lst
  See Bazaar.launchpad.net
• rttr.Chat(player, message...)
  Sends message to player (-1 for all players).
• rttr.Log(message...)
  Log to console.
• rttr.PostMessage(player, message...)
  Send post message to player.
• rttr.PostMessageWithLocation(player, x, y, message...)
  Send post message to player (with location x, y).
• PostNewBuildings(player, building_type...)
  Inform player that he can now build building_type.
• rttr.GetPlayerCount()
  Returns number of players.
• rttr.GetPeopleCount(player, job_type)
  Get number of people a player has with a given job.
• rttr.GetWareCount(player, ware_type)
  Get number of wares a player has of a given type.
• rttr.GetBuildingCount(player, building_type)
  Get number of buildings a player has of a given type.
• rttr.MissionStatement(player, title, message...)
  Send mission statement to player:
  rttr.MissionStatement(0, "Diary", "Forth day\n\n\nThere are ", rttr.GetBuildingCount(0, BLD_WELL), " wells now.")

A list of valid building IDs (BLD_*), ware IDs (GD_*) and job IDs (JOB_*) may be found here:
Bazaar.launchpad.net
However you are encouraged to use the predefined variables (see example below).

Below you'll find an example for TAL018.SWD (Atomium I, 3 players):

-- start callback, called after everything is set up
function onStart()
    -- add 100 generals and 10 officers for player 0
    rttr.AddPeople(0, JOB_GENERAL, 100, JOB_OFFICER, 10)
end

function onGameFrame(no)
    -- every 100 gf...
    if no % 100 == 0 then
        -- for all players..
        for player = 0, rttr.GetPlayerCount() - 1 do
            rttr.Chat(0xFFFFFFFF, "[Player ", player, " @GF ", rttr.GetGF() , "] helpers: ", rttr.GetPeopleCount(player, JOB_HELPER), ", wells: ", rttr.GetBuildingCount(player, BLD_WELL), ", water: ", rttr.GetWareCount(player, GD_WATER))
        end
    end
end

-- just output a message on stdout for now
function onOccupied(p, x, y)
    io.write("Point occupied: ", p, ": ", x, ",", y, "n")
end

-- just output a message on stdout for now
function onExplored(p, x, y)
    io.write("Point explored: ", p, ": ", x, ",", y, "n")
end

-- disable barracks (building 1) for player 0
rttr.DisableBuilding(0, BLD_BARRACKS)

-- restrictions for player 0
rttr.SetRestrictedArea(0, 0,42, 255,42, 255,255, 0,255)

Please be aware that the support is experimental at the moment and invalid values from scripts may lead to crashes. Please do not report a bug in this case. This especially applies for area restrictions, as it is necessary that everything a player owns is inside that area. Otherwise the game may crash. Therefore, restricted area should be set at script load time (not in the start() event callback or even later) and include at least the headquarter, but not necessarily the land gained by it. Afterwards the area should only be increased.

That's all for now.