Settlers 6 S6_SEED_ScriptTutorials.

doc

SE|ED
Settlers Editor

Script Tutorials

11 December 2007 15:35

Page 1 of 14

Settlers 6 S6_SEED_ScriptTutorials.doc

SE|ED Settlers Editor

Script-Tutorials
Content:
Page

1. In General 2. Trade Partners & Mercenaries 3. Additional Settings for Trade Partners 4. AI Building Order 5. Occupation of Outposts 6. Viking Marine Attack 7. Interactive Objects, Ruins 8. Limiting Titles and Technologies 9. Victory Celebration 10. Waypoints

3 3 5 6 7 8 9 11 13 14

11 December 2007 15:35

Page 2 of 14

Settlers 6 S6_SEED_ScriptTutorials.doc

1. In General
In order to execute the tutorials described here, you have to activate the expert mode of the editor. Please consider that while working in the expert mode heavy problems may occur that are not very comprehensible. a) Export the existing script: Select the menu item Expert Mode > Export Map Script. b) Adjust your script with an editor suitable for Lua, e.g. Notepad++. c) Import the amended map script: Select the menu item Expert Mode > Import Map Script. From Patch 1.3, this also displays possible syntax errors including the respective line number.

2. Trade Partners & Mercenaries

In order to make existing villages, cloisters or bandit camps trade partners that offer goods or mercenaries, you need to enter a few lines into an existing function. a) Look for the following function (it will probably be empty): function Mission_InitMerchants() end b) Now enter the desired trade partners and goods into the InitMerchants function. Please keep in mind that there may only be a maximum of 4 offers per trade partner: function Mission_InitMerchants() local traderId = Logic.GetStoreHouse(AIPlayerID) AddOffer( traderId, NumberOfOffers, GoodType ) end The cursive variable names have to be replaced by your own values: AIPlayerID: NumberOfOffers: GoodType: ID of the AI player offering the deal. Number of offers. Type of offered commodities. The respective commodities can be taken from the following list. Each value entered here needs to be preceded by Goods..

G_Beer G_Bow G_Bread G_Broom G_Candle G_Carcass G_Cheese G_Clothes G_Cow G_Grain G_Herb G_Honeycomb G_Iron G_Leather G_Medicine G_Milk G_RawFish G_Sausage G_Sheep G_SmokedFish G_Soap G_Stone G_Sword G_Wood G_Wool Example for a trade partner (village with storehouse) with the Player ID 3 offering 2 Wood, 3 Iron, 5 Cows and 5 Sheep: function Mission_InitMerchants() local traderId = Logic.GetStoreHouse(3) AddOffer( traderId, 2, Goods.G_Wood ) AddOffer( traderId, 3, Goods.G_Iron ) AddOffer( traderId, 5, Goods.G_Cow ) AddOffer( traderId, 5, Goods.G_Sheep ) end

11 December 2007 15:35

Page 3 of 14

Settlers 6 S6_SEED_ScriptTutorials.doc

Next to the commodities, mercenaries may also be on offer. But do remember that there may only be a maximum of 4 commodity and/or mercenary offers per trade partner.

It is quite helpful to use the editor to place barracks (e.g. B_NPC_Barracks_ME) in a village that is supposed to offer mercenaries. This is not compulsive, but it is a nice visualisation for the player. If you edit barracks for an NPC-village, it will also be patrolled by mercenaries (if you also erect palisades with a gate around the village).

Mercenaries can be added with this cue: AddMercenaryOffer( traderId, Amount, UnitType) Amount: Number of offered mercenaries. UnitType: Type of offered units. The specific types can be taken from the following list. Each value entered here needs to be preceded by Entities.. U_MilitaryBandit_Melee_ME U_MilitaryBandit_Melee_SE U_MilitaryBandit_Melee_NA U_MilitaryBandit_Melee_NE U_MilitaryBandit_Ranged_ME U_MilitaryBandit_Ranged_NA U_MilitaryBandit_Ranged_NE U_MilitaryBandit_Ranged_SE U_MilitaryBow U_MilitaryBow_RedPrince U_MilitarySword U_MilitarySword_RedPrince Example for a bandit camp (with BanditsHQ) with the Player ID 3, which will offer 2 groups of archers and 3 groups of swordsmen as mercenaries: function Mission_InitMerchants() local traderId = Logic.GetStoreHouse(3) AddMercenaryOffer( traderId, 2, Entities.U_MilitaryBandit_Melee_ME ) AddMercenaryOffer( traderId, 3, Entities.U_MilitaryBandit_Ranged_ME ) end In addition to commodities and mercenaries, you may also hire fire-eaters for your marketplace. Use the following line for that: AddEntertainerOffer ( traderId, Entities.U_FireEater )

11 December 2007 15:35

Page 4 of 14

Settlers 6 S6_SEED_ScriptTutorials.doc

3. Further Settings for Trade Partner

Normally, you can trade with any player scheduled for it once you achieved a diplomatic trade relationship. In some cases, you might still want to periodically stop the trade relation, e.g. when the trade route is threatened by dangerous wolves. You can control the purchase and sale of commodities and mercenaries. The respective functions can be activated at a random location in the script, where you want to change the trade behaviour. To make sure that the respective lines work, they have to be preceded by the following line: local traderId = Logic.GetStoreHouse(AIPlayerID) Stop offer: DeActivateMerchantForPlayer( traderId, PlayerID ) Activate offer again for knight: ActivateMerchantForPlayersKnight( traderId, PlayerID ) Always activate offer: ActivateMerchantPermanentlyForPlayer( traderId, PlayerID ) Control purchase of goods: SetPlayerDoesNotBuyGoodsFlag( AIPlayerID, Active )

a) AIPlayerID: AI Player ID of player, whose trade settings need to be altered. b) PlayerID: Player ID. It is usually 1. c) Active: This (de)activates the purchase of goods. Possible values are true (does not
purchase goods) and false (will buy goods). Example for a function preventing trade with Player 2: function DeactivateTradeWithPlayer2() local traderId = Logic.GetStoreHouse( 2 ) DeActivateMerchantForPlayer( traderId, 1 ) SetPlayerDoesNotBuyGoodsFlag( 2, true ) end

11 December 2007 15:35

Page 5 of 14

Settlers 6 S6_SEED_ScriptTutorials.doc

4. AI Building Oder
The order in which the AI will construct buildings in Settlers 6 is defined by the AI-Building Order set in the editor under building properties (numbers 1 to X). With the help of this function you can define up to which AI Building Order the AI will construct buildings. Simply complete this line in Mission_InitPlayers(). If it is added in other places and e.g. activated after a certain amount of time, this will help to create a gradual build-up process of the AI. If the line is not used, the AI will construct all buildings placed in the map editor. AICore.SetNumericalFact( AIPlayerID, "BPMX", AIBuildingOrder ) AIPlayerID: ID of the AI player, whose build-up should be controlled. AIBuildingOrder: The last level of buildings to be constructed by the AI.

Example for the AI player with the ID 3, who will construct a woodcutters hut and a hunting lodge: Use the map editor to place 3 buildings on the territory of the AI player and assign them the correct Player ID 2 woodcutters huts and a hunting lodge. By double-clicking the created buildings, you display the menu Properties. Here you enter the value 1 in AI Building Order for the hunting lodge and one of the woodcutters huts. The second woodcutter gets 2. function Mission Mission_InitPlayers() AICore.SetNumericalFact( 3, "BPMX", 1 ) end If later on SetNumericalFact is activated with the number 2, the second woodcutters hut is also constructed. As walls cannot be assigned an AI Building Order in the map editor, you can set it via the script. Simply add the following function to your script: function GameCallback_AIWallBuildingOrder(_PlayerID) if _PlayerID == AIPlayerID then return AIBuildingOrder end end You can use the parameters described above to decide during which building level the walls should be constructed. If you do not want destroyed buildings to be rebuilt automatically, you need to execute the following line one: AICore.SetNumericalFact( AIPlayerID, "BARB", 0 )

11 December 2007 15:35

Page 6 of 14

Settlers 6 S6_SEED_ScriptTutorials.doc

5. Occupation of Outposts
If the AI player possesses additional territories with outposts from the start, these are not protected by military units and can thus be easily occupied by the other players. In order to protect an outpost with a troop of archers, you first have to name the outpost, e.g. Outpost1. Then you enter the following cue into Mission_FirstMapAction() with the respectively changed names: MountOutpostWithArchers( "Outpost1" ) In order to be able to use this cue, you have to enter the following function once in a free slot in the map script (not within another function): function MountOutpostWithArchers( _Outpost ) local outpostID = assert( Logic.GetEntityIDByName(_Outpost) ) local AIPlayerID = Logic. EntityGetPlayer(outpostID) local ax, ay = Logic.GetBuildingApproachPosition(outpostID) local TroopID = Logic.CreateBattalionOnUnblockedLand( Entities.U_MilitaryBow, ax, ay, 0, AIPlayerID, 0 ) AICore.HideEntityFromAI( AIPlayerID, TroopID, true ) Logic.CommandEntityToMountBuilding( TroopID, outpostID ) end The entered function does not have to be changed.

11 December 2007 15:35

Page 7 of 14

Settlers 6 S6_SEED_ScriptTutorials.doc

6. Viking Marine Attack

Vikings will not attack the players special buildings (castle, storehouse, cathedral, and marketplace). Resource gatherers or town buildings may be set on fire though. To make sure that everything works, you need to place a few script entities in the map editor for the Player ID of the Viking AI player (via Place Entities > Script): XD_ScriptEntity with the script name VikingsShipStart. This is where the Viking ship will appear. XD_ScriptEntity with the script name VikingsShipEnd in vicinity of beach. The Viking ship will sail to this point before the attack. S_AIHomePosition close to the beach where the Vikings are supposed to land. XD_ScriptEntity with the script name VikingsSpawnPoint in a walkable beach area. This is where the Vikings will leave their boat. Optionally a XD_ScriptEntity with the script name VikingsTarget. If no such target is set, the Vikings will pick it for themselves.

Look for the function Mission_InitPlayers() in your map script. Add the following script block to the function: Viking = AIPlayer:new( AIPlayerID, AIPlayerProfile_Viking ) Viking.m_ShipSpawnID = Logic.GetEntityIDByName("VikingsShipStart") Viking.m_ShipEndID = Logic.GetEntityIDByName("VikingsShipEnd") Viking.m_VikingSpawnID = Logic.GetEntityIDByName("VikingsSpawnPoint") Viking.m_NumberOfVikings = NumberOfAttackers Viking.m_StartAttackMonth = Month -- The following line is only necessary if a target was set Viking.m_TargetID = Logic.GetEntityIDByName("VikingsTarget") AIPlayerID: A free Player ID. There should not be any buildings or units with this Player ID. NumberOfAttackers: Number of Viking units created after the ship has landed. 8 units are usually sufficient to destroy a woodcutters hut. Month: corresponds to the month the Viking attack is triggered.

11 December 2007 15:35

Page 8 of 14

Settlers 6 S6_SEED_ScriptTutorials.doc

7. Interactive Objects, Ruins

An interactive object with the script name IO1 can be configured with the following lines, which could be inserted into Mission_FirstMapAction(). IOID = Logic.GetEntityIDByName("IO1") Logic.InteractiveObjectSetPlayerState(IOID, PlayerID, Use1 ) Logic.InteractiveObjectSetAvailability(IOID, Use2 ) Logic.InteractiveObjectSetInteractionDistance(IOID, Distance ) Logic.InteractiveObjectSetTimeToOpen(IOID, Time ) Logic.InteractiveObjectClearCosts(IOID) Logic.InteractiveObjectClearRewards(IOID) Logic.InteractiveObjectAddCosts(IOID, CostGood, CostAmount ) Logic.InteractiveObjectSetCostGoldCartType( ID, GoldCart ) Logic.InteractiveObjectSetCostResourceCartType( ID, GoodCart ) The following three lines are only required, if the player is supposed to receive resources from the interactive object: Logic.InteractiveObjectAddRewards(IOID, RewardGood, RewardAmount ) Logic.InteractiveObjectSetRewardGoldCartType( ID, GoldCart ) Logic.InteractiveObjectSetRewardResourceCartType( ID, GoodCart ) The following three lines are only required, if the interactive object is supposed to be replaced by another object: Logic.InteractiveObjectSetReplacingEntityType( IOID, Replace )

PlayerID: ID of the player, for whom the interactive object is supposed to (not) be usable. In general, this is 1. Use1: Type of use: 0 - can only be used by a knight. 1 can always be used. 2 cant ever be used. Use2: This globally (de)activates the possibility for use. Possible values are true (active) and false (not active). Distance: Distance from which a knight can activate the object. Usually, values between 1000 and 2000 are applied. Time: Time in seconds until the object can be activated after a knight has come into range. CostGood and RewardGood: Resource needed for the activation, or resource given after activation. A respective list can be found in paragraph 2. Not all resources can be used faultlessly. Wood or gold are often entered here. CostAmount and RewardAmount: Amount of gold to be paid by the player for activation, or to be received after activation. GoldCart and GoodCart: Cart supposed to be used for transport of the respective resource (do not forget to precede by Entities.). Possibilities are: U_GoldCart U_Noblemen_Cart U_RegaliaCart U_ThiefCart U_ResourceMerchant Replace: Building to replace the interactive object after activation. This is usually used for signal fires (see example on next page).

11 December 2007 15:35

Page 9 of 14

Settlers 6 S6_SEED_ScriptTutorials.doc

In the following an example for an ignitable signal fire that at first cannot be used. Later on, it can be activated by a certain incident. Afterwards, it can be lit by the knight of Player 1 after a preparation time of 10 seconds. It costs 20 wood and 5 gold (the resource cart driver wants to be paid after all) to light the signal fire. After the signal fire has been lit, a stone from the fire as well as remaining gold is picked up. As a preparation, you need to place a signal fire (I_X_SignalFire_Base) with the script name SignalFire in the map editor under Place Entities > Interactive Objects. function Mission_FirstMapAction() SignalFireID = Logic.GetEntityIDByName("SignalFire") Logic.InteractiveObjectSetPlayerState( SignalFireID, 1, 2 ) Logic.InteractiveObjectSetAvailability( SignalFireID, false ) end function Activate_SignalFireID() SignalFireID = Logic.GetEntityIDByName("SignalFire") Logic.InteractiveObjectSetPlayerState( SignalFireID, 1, 0 ) Logic.InteractiveObjectSetAvailability( SignalFireID, true ) Logic.InteractiveObjectSetInteractionDistance( SignalFireID, 1500 ) Logic.InteractiveObjectSetTimeToOpen( SignalFireID, 10 ) Logic.InteractiveObjectClearCosts(SignalFireID) Logic.InteractiveObjectAddCosts( SignalFireID, Goods.G_Wood, 20 ) Logic.InteractiveObjectAddCosts( SignalFireID, Goods.G_Gold, 5 ) Logic.InteractiveObjectSetCostGoldCartType( ID, Entities.U_GoldCart) Logic.InteractiveObjectSetCostResourceCartType( ID, Entities.U_ThiefCart ) Logic.InteractiveObjectClearRewards(SignalFireID ) Logic.InteractiveObjectAddRewards( ID, Goods.G_Stone, 1 ) Logic.InteractiveObjectAddRewards( ID, Goods.G_Gold, 1 ) Logic.InteractiveObjectSetRewardGoldCartType( ID, Entities.U_GoldCart ) Logic.InteractiveObjectSetRewardResourceCartType( ID, Entities.U_ThiefCart ) Logic.InteractiveObjectSetReplacingEntityType( SignalFireID, Entities.D_X_SignalFire_Fire ) end If you do not want to add an event to activate Activate_SignalFireID(), you could also activate it from the last line in Mission_FirstMapAction().

11 December 2007 15:35

Page 10 of 14

Settlers 6 S6_SEED_ScriptTutorials.doc

8. Limiting Titles & Technologies

On some maps it makes sense to limit the maximum achievable title to not make the map too easy. You could also block some technologies in the beginning, which could be unlocked by fulfilling a certain quest. With this line you set the title that the player cannot achieve anymore. This line is usually added to Mission_InitPlayers(). LockTitleForPlayer( PlayerID, Title ) PlayerID: ID of player. Usually 1. Title: The title, which the player cannot achieve anymore. Each title entered here needs to be preceded by KnightTitles.. You can use the following titles: Knight Mayor Baron Earl Marquis Duke Archduke

Example limiting the player to the construction of basic buildings. Also, he cannot be promoted any further: LockTitleForPlayer( 1, KnightTitles.Mayor )

While the blockage of the knights title may not be reversed with existing functions, technologies may be blocked and unblocked just as you desire. Hence you can enter the cue everywhere you want to alter the use of technologies: local TechologiesToChange = { Tech, Tech, } The following line is only necessary, if technologies are to be blocked: LockFeaturesForPlayer( PlayerID, TechologiesToChange ) The following line is only necessary, if technologies are to be unblocked again: UnLockFeaturesForPlayer( PlayerID, TechologiesToChange) PlayerID: ID of player. Usually 1. Tech: Technology to be altered. Each technology entered here needs to be preceded by Technologies.. You can use the following technologies:

R_AmmunitionCart R_Bakery R_Ballista R_BannerMaker R_Barracks R_BarracksArchers R_Baths R_BatteringRam R_Beekeeper R_Blacksmith R_BowMaker R_BroomMaker R_BuildingUpgrade R_Butcher R_CandleMaker R_Carpenter R_Castle_Upgrade_1 R_Castle_Upgrade_2 R_Castle_Upgrade_3 R_Catapult R_Cathedral_Upgrade_1 R_Cathedral_Upgrade_2 R_Cathedral_Upgrade_3 R_CattleFarm R_Clothes R_Construction R_Dairy R_Entertainment R_Festival R_FishingHut R_Gathering R_GrainFarm R_HerbGatherer R_HuntersHut R_Hygiene R_IronMine R_KnockDown R_Medicine R_Military R_Nutrition R_Pallisade R_Prosperity R_Sermon R_SheepFarm R_SiegeEngineWorkshop R_SiegeTower R_SmokeHouse R_Soapmaker R_StoneQuarry R_Storehouse_Upgrade_1 R_Storehouse_Upgrade_2 R_Storehouse_Upgrade_3 R_Street R_SwordSmith
11 December 2007 15:35 Page 11 of 14

Settlers 6 S6_SEED_ScriptTutorials.doc

R_Tanner R_Tavern R_Taxes R_Theater R_Thieves R_Trade R_Trail R_Victory R_Wall R_Wealth R_Weaver R_Woodcutter Example with blocked hunter and fishermen: local TechologiesToLock = { Technologies.R_HuntersHut, Technologies.R_FishingHut, } LockFeaturesForPlayer( 1, TechologiesToLock ) Example in which the technologies blocked earlier may be unblocked again later by activating the function:

function UnlockTechs() local TechologiesToLock = { Technologies.R_HuntersHut, Technologies.R_FishingHut, } UnLockFeaturesForPlayer( 1, TechologiesToLock ) end

11 December 2007 15:35

Page 12 of 14

Settlers 6 S6_SEED_ScriptTutorials.doc

9. Victory Celebration
There are a few possibilities for special actions after winning a map. One of those is the victory celebration, during which the players knight might be present as well. In order to set the knights position for the festival, you need to place a script entity called VictoryKnightPos in the direct vicinity of the marketplace. Afterwards, you need to add a new function to the map script: function Mission_Victory() local PossibleSettlerTypes = { Entity, Entity, } VictoryGenerateFestivalAtPlayer( PlayerID, PossibleSettlerTypes ) local VictoryKnightPos = Logic.GetEntityIDByName("VictoryKnightPos") local x,y = Logic.GetEntityPosition(VictoryKnightPos) local Orientation = Logic.GetEntityOrientation(VictoryKnightPos) local KnightID = Logic.GetKnightID(1) VictorySetEntityToPosition( KnightID, x, y, Orientation ) end PlayerID: ID of the victorious player. Usually 1. Entity: A settler who could be present during the festival. Here you could list several different settlers. Each value entered here needs to be preceded by Entities.. You could use the following values:

U_NPC_Monk_ME U_NPC_Monk_NE U_NPC_Monk_NA U_NPC_Monk_SE U_NPC_Villager01_ME U_NPC_Villager01_NE U_NPC_Villager01_SE U_NPC_Villager01_NA U_Baker U_BathWorker U_Soapmaker U_DairyWorker U_HerbGatherer U_GrainFarmer U_CattleFarmer U_Woodcutter U_SheepFarmer U_Weaver U_BannerMaker U_Beekeeper U_Barkeeper U_IronMiner U_Stonecutter U_Fisher U_Hunter U_SmokeHouseWorker U_Butcher U_Pharmacist U_BroomMaker U_Tanner U_Priest U_Blacksmith U_CandleMaker U_Carpenter U_Actor_Nobleman U_Actor_Bandit U_Actor_Princess U_TheatreWorker U_SpouseS01 U_SpouseS02 U_SpouseS03 U_SpouseF01 U_SpouseF02 U_SpouseF03 Example for a small victory celebration with only fishermen, woodcutters and their spouses as guests, not the players knight: function Mission_Victory() local PossibleSettlerTypes = { Entities.U_Fisher, Entities.U_Woodcutter, Entities.U_SpouseS01, Entities.U_SpouseF01, } VictoryGenerateFestivalAtPlayer( 1, PossibleSettlerTypes ) end

11 December 2007 15:35

Page 13 of 14

Settlers 6 S6_SEED_ScriptTutorials.doc

10. Waypoints
NPCs may pass defined waypoints in different ways. First, you need to place an NPC (Units -> NPCs) and its respective waypoints in the form of script entities in the map editor and name them. It is also possible to use named buildings as waypoints, but problems may occur in combination with other settings. The code for the waypoints is pasted into a suitable place in the script, this is usually Mission_FirstMapAction(). local Entity = Logic.GetEntityIDByName(NPCName) local ControlPointsList = { WPName1, WPName2 } Path:new( Entity, ControlPointsList, Loop, Back, OnArrival, OnReturn, nil, LoopCallback, nil, Distance ) NPCName: Script name of NPC. WPName: Name of set waypoints. All following values are optional: Loop: If this is set to true, the NPC will walk to the first waypoint again as soon as the last set waypoint has been reached. Then the waypoints are passed again. Back: If this is set to true, the NPC will go back the way he came once he reached the end point, passing all waypoints until he reaches the start point again. OnArrival: A unique function that is activated once the NPC reaches his destination (the last waypoint). OnReturn: A unique function that is activated once the NPC (with Back = true) has walked back to the first waypoint. LoopCallback: A unique function that is activated every second, as long as the NPC follows the path. Distance: Determines how close the NPC has to get to a waypoint in order to consider this waypoint as reached.

Example for an NPC with the name NPC1, who walks once from NPC1_WP0 to NPC1_WP1: local Entity = Logic.GetEntityIDByName("NPC1") local ControlPointsList = { "NPC1_WP0", "NPC1_WP1" } Path:new( Entity, ControlPointsList ) Example for an NPC called NPC2, who walks from NPC2_WP0 via NPC2_WP1 to NPC2_WP2, then turns around and walks back to the start point. The NPC has to get as close as 99 cm to each waypoint: local Entity = Logic.GetEntityIDByName("NPC2") local ControlPointsList = { "NPC1_WP0", "NPC1_WP1", "NPC1_WP2" } Path:new( Entity, ControlPointsList, nil, true, nil, nil, nil, nil, nil,99)

11 December 2007 15:35

Page 14 of 14