Author: alpaca
Original Thread: The Script-o-Rama

The Script-o-RamaThe script-o-rama is supposed to be a thread about scripting. This thread will serve a few different purposes:
Firstly it's meant as a general scripting discussion point, so if you'd like to just talk about some freak ideas or anything, they're welcome here.
Secondly, I will post stuff like tutorials or little tidbits of information about scripting here, so it'll also turn into a kind of info collection for scripting.
Last and least, if you want to ask me personally some questions, you'd best do it here as I don't particularly like answering them via PM where everything is secret.

Section I: Reference

This section will contain some short descriptions about functions and objects that are exposed to LuA. Let me start with a list compiled by just that you can get by calling getfenv():

http://www.twcenter.net/forums/showthread.php?t=243201

Now let's get to the action. I'll put this in alphabetical order.

General Notes

Case sensitivity:
All LuA functions and objects are case-sensitive. That is, CampaignUI is not equal to campaignui, campaignUi or anything like that.

I.1 Object: Effects

adjust_treasury(int amount, context faction)
effect.adjust_treasury will change the treasury of a certain faction.
Spoiler Alert, click show to read: 

Parameters: Amount of money, faction context

Example:
Code:
events.FactionTurnStart[#events.FactionTurnStart+1] =
function (context)
	effect.adjust_treasury(-1000,context)
end


I.2 Object: Campaign UI
CampaignUI seems to have loads of useful functions (see the list above). Any that I can confirm to work will be listed below.

CurrentSeasonString()
Calling CampaignUI.CurrentSeasonString() will return the current season as a string.
Spoiler Alert, click show to read: 
Returns: Current season as string. One of Summer or Winter

Example:
Code:
CampaignUI.CurrentSeasonString() == "Summer"
Notes:
Be careful about case sensitivity


CurrentTurn()
Calling CampaignUI.CurrentTurn() will return the current turn number.
Spoiler Alert, click show to read: 
Returns: Current turn as int.

Example:
Code:
CampaignUI.CurrentTurn() == 0


CurrentYear()
Calling CampaignUI.CurrentYear() will return the current year.
Spoiler Alert, click show to read: 
Returns: Current year as int.

Example:
Code:
CampaignUI.CurrentYear() >= 1700


DisplayingTurns()
Calling CampaignUI.DisplayingTurns() will tell you if the game is displaying years or turns.
Spoiler Alert, click show to read: 
Returns: Boolean: true if displaying turns, false if displaying years

Example:
Code:
if CampaignUI.DisplayingTurns() then
...
end


EndTurn()
Calling CampaignUI.EndTurn() will end the turn.
Spoiler Alert, click show to read: 
Example:
Code:
CampaignUI.EndTurn()


EntityTypeSelected()
CampaignUI.EntityTypeSelected() will give you information about the currently selected game entity
Spoiler Alert, click show to read: 
Returns: Entity details table. Important here is CampaignUI.EntityTypeSelected().Entity which holds a pointer (e.g. a Character Pointer) that can be used in other functions

Example:
Code:
CampaignUI.EntityTypeSelected()
Will return a table containing this info:
Code:
  Character: boolean: true
  Unit: boolean: false
  Slot: boolean: false
  Settlement: boolean: false
  Entity: userdata
    type: string: Pointer<CHARACTER>
    __tostring: function
    __eq: function
  LocalPlayerOwned: boolean: true
  Fort: boolean: false


FactionDetails(string faction_key)
CampaignUI.FactionDetails() will give you information about a certain faction.
Spoiler Alert, click show to read: 
Arguments: Faction ID string

Returns: Faction details table

Example:
Code:
CampaignUI.FactionDetails("britain")
Will return a table containing this info:
Code:
  VictoryConditions: table
    Regions: table
      1: table
        Name: string:New France
        Address: userdata
          type: string:Pointer<REGION>
          __tostring: function
          __eq: function
      2: table
        Name: string:Georgia
        Address: userdata
          type: string:Pointer<REGION>
          __tostring: function
          __eq: function
      3: table
        Name: string:Leeward Islands
        Address: userdata
          type: string:Pointer<REGION>
          __tostring: function
          __eq: function
      4: table
        Name: string:Ireland
        Address: userdata
          type: string:Pointer<REGION>
          __tostring: function
          __eq: function
      5: table
        Name: string:Gibraltar
        Address: userdata
          type: string:Pointer<REGION>
          __tostring: function
          __eq: function
      6: table
        Name: string:Florida
        Address: userdata
          type: string:Pointer<REGION>
          __tostring: function
          __eq: function
      7: table
        Name: string:Hindustan
        Address: userdata
          type: string:Pointer<REGION>
          __tostring: function
          __eq: function
      8: table
        Name: string:Scotland
        Address: userdata
          type: string:Pointer<REGION>
          __tostring: function
          __eq: function
      9: table
        Name: string:England
        Address: userdata
          type: string:Pointer<REGION>
          __tostring: function
          __eq: function
    ConquestDescription: string:Capture and hold 25 regions by the end of the year 1750, including the regions shown.
    TotalRegionsNeeded: number
    PrestigeDescription: string:
  WealthRanking: string:Spectacular
  Leader: table
    ActionPointsPerTurn: number
    Flag: string:data\ui\flags\britain/portrait_flags.tga
    Title: string: 
    Traits: table
      1: table
        ExplanationText: string:This man has invested heavily in the navy.
        IconFilename: string:data/ui/campaign ui/pips/effect_characters.tga
        Name: string:Likes Uniforms
        Effects: table
          1: table
            Priority: number
            Description: string:-10% recruitment cost for all naval units
            IconFilename: string:data/ui/campaign ui/pips/effect_navy.tga
        ColourText: string:He has taken to wearing ceremonial uniforms at all times, which makes bathing a difficult business.
        AttributeEffects: table
        RemovalText: string:This trait can be lost by more balanced spending.
      2: table
        ExplanationText: string:Youthful obsessions are one thing, but they are supposed to be set aside.
        IconFilename: string:data/ui/campaign ui/pips/effect_characters.tga
        Name: string:Lewd and Loose
        Effects: table
          1: table
            Priority: number
            Description: string:-10 to diplomatic relations
            IconFilename: string:
        ColourText: string:This man's behaviour is boorish and nationally embarrassing, even if the ambassador's wife did have a fantastic arse!
        AttributeEffects: table
        RemovalText: string:This man's ways are set, unfortunately.
    Effects: table
      1: table
        Icon: string:
        Tooltip: string:-10 to diplomatic relations
      2: table
        Icon: string:data/ui/campaign ui/pips/effect_navy.tga
        Tooltip: string:-10% recruitment cost for all naval units
    PostEffects: table
      diplomacy: table
        Value: number
        Description: string:+0 to diplomatic relations
      prestige: table
        Value: number
        Description: string:+0 Prestige per turn
    FactionColour: table
      b: number
      g: number
      r: number
    ShowAsCharacter: boolean
    IsMilitary: boolean
    Attributes: table
      morale_sea: table
        Value: number
        AttributeName: string:Morale
        PipPath: string:PLACEHOLDER
      research: table
        Value: number
        AttributeName: string:Research Skill
        PipPath: string:data/ui/campaign ui/pips/skill_research.tga
      land_siege_engineering: table
        Value: number
        AttributeName: string:Siege engineering
        PipPath: string:PLACEHOLDER
      movement_points_land: table
        Value: number
        AttributeName: string:movement_points_land_name
        PipPath: string:PLACEHOLDER
      management: table
        Value: number
        AttributeName: string:Management Skill
        PipPath: string:data/ui/campaign ui/pips/skill_managing.tga
      PrimaryAttributePath: string:data/ui/campaign ui/pips/skill_managing.tga
      PrimaryAttributeName: string:Management Skill
      zeal: table
        Value: number
        AttributeName: string:Religious Zeal
        PipPath: string:data/ui/campaign ui/pips/skill_zeal.tga
      subterfuge: table
        Value: number
        AttributeName: string:Subterfuge Skill
        PipPath: string:data/ui/campaign ui/pips/skill_spying.tga
      duelling_swords: table
        Value: number
        AttributeName: string:Sword duelling
        PipPath: string:data/ui/campaign ui/pips/skill_swordfighting.tga
      duelling_pistols: table
        Value: number
        AttributeName: string:Pistol duelling
        PipPath: string:data/ui/campaign ui/pips/skill_shooting.tga
      morale_land: table
        Value: number
        AttributeName: string:Morale
        PipPath: string:PLACEHOLDER
      trade: table
        Value: number
        AttributeName: string:Trade
        PipPath: string:PLACEHOLDER
      PrimaryLevel: number
      land_defence_engineering: table
        Value: number
        AttributeName: string:Land defence engineering
        PipPath: string:PLACEHOLDER
      command_sea: table
        Value: number
        AttributeName: string:Command at Sea
        PipPath: string:data/ui/campaign ui/pips/skill_naval.tga
      command_land: table
        Value: number
        AttributeName: string:Command on Land
        PipPath: string:data/ui/campaign ui/pips/skill_command.tga
    Abilities: table
      can_research: boolean
      can_assassinate: boolean
      can_attack_naval: boolean
      can_build_religious: boolean
      can_attack_land: boolean
      can_receive_duel: boolean
      can_build_fort: boolean
      can_duel: boolean
      can_convert: boolean
      can_sabotage: boolean
      can_spy: boolean
    PostName: string:King
    CommanderType: number
    ActionPoints: number
    Post: string:faction_leader
    AgentType: string:Minister
    IsNaval: boolean
    SmallFlag: string:data\ui\flags\britain/small.tga
    UniformColour: table
      b: number
      g: number
      r: number
    MaskImage: string:
    TechImage: string:
    Playable: boolean
    CardImage: string:data/ui/portraits/european/cards/king/old/014.tga
    InfoImage: string:data/ui/portraits/european/Info/king/old/014.jpg
    Address: userdata
      type: string:Pointer<CHARACTER>
      __tostring: function
      __eq: function
    Location: string:England
    Name: string:William III
    Age: number
    Ancillaries: table
  PrestigeRanking: string:Sublime
  FlagPath: string:data\ui\flags\britain
  UniformColour: table
    B: number
    G: number
    R: number
  Address: userdata
    type: string:Pointer<FACTION>
    __tostring: function
    __eq: function
  Name: string:Great Britain
  PrimaryColour: table
    B: number
    G: number
    R: number
  Key: string:britain
  PowerRanking: string:Terrifying


IsCharacterPlayerControlled(CharacterPointer pointer)
CampaignUI.IsCharacterPlayerControlled() will tell you whether a character is controlled by the player.
Spoiler Alert, click show to read: 

Returns: boolean true or false

Example:
Code:
entity = CampaignUI.EntityTypeSelected()
if entity.Character then
	if CampaignUI.IsCharacterPlayerControlled(entity.Entity) then
		...
	end
end


PlayerFactionId()
Calling CampaignUI.PlayerFactionId() will return the player's faction key.
Spoiler Alert, click show to read: 
Returns: Faction ID as a string, e.g. "britain"

Example:
Code:
CampaignUI.PlayerFactionId() == "britain"


PrestigeDetails()
CampaignUI.PrestigeDetails() will give you access to the prestige points for each faction
Spoiler Alert, click show to read: 

Returns: Prestige details table

Example:
Code:
CampaignUI.PrestigeDetails()
Will return a table containing this info:
Code:
 scale: number: 34
  factions: table
    1: table
      faction_colour: table
        b: number: 0
        g: number: 0
        r: number: 0.8705883026123
      history: table
        1: table
          military: number: 5
          overall: number: 30
          enlightenment: number: 5
          naval: number: 10
          economics: number: 10
        2: table
          military: number: 5
          overall: number: 30
          enlightenment: number: 5
          naval: number: 10
          economics: number: 10
        3: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        4: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        5: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        6: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
      name: string: Great Britain
      is_enemy: boolean: false
      is_neighbouring: boolean: false
      key: string: britain
      flag_path: string: data\ui\flags\britain
      is_ally: boolean: false
    2: table
      faction_colour: table
        b: number: 0.94117653369904
        g: number: 1
        r: number: 1
      history: table
        1: table
          military: number: 18
          overall: number: 34
          enlightenment: number: 4
          naval: number: 5
          economics: number: 7
        2: table
          military: number: 18
          overall: number: 34
          enlightenment: number: 4
          naval: number: 5
          economics: number: 7
        3: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        4: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        5: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        6: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
      name: string: France
      is_enemy: boolean: false
      is_neighbouring: boolean: false
      key: string: france
      flag_path: string: data\ui\flags\france
      is_ally: boolean: false
    3: table
      faction_colour: table
        b: number: 0.33725491166115
        g: number: 0.56470590829849
        r: number: 0.64705884456635
      history: table
        1: table
          military: number: 17
          overall: number: 24
          enlightenment: number: 0
          naval: number: 0
          economics: number: 7
        2: table
          military: number: 17
          overall: number: 24
          enlightenment: number: 0
          naval: number: 0
          economics: number: 7
        3: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        4: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        5: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        6: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
      name: string: Austria
      is_enemy: boolean: false
      is_neighbouring: boolean: false
      key: string: austria
      flag_path: string: data\ui\flags\austria
      is_ally: boolean: true
    4: table
      faction_colour: table
        b: number: 0.11372549831867
        g: number: 0.5137255191803
        r: number: 1
      history: table
        1: table
          military: number: 0
          overall: number: 23
          enlightenment: number: 5
          naval: number: 5
          economics: number: 13
        2: table
          military: number: 0
          overall: number: 23
          enlightenment: number: 5
          naval: number: 5
          economics: number: 13
        3: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        4: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        5: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        6: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
      name: string: United Provinces
      is_enemy: boolean: false
      is_neighbouring: boolean: false
      key: string: netherlands
      flag_path: string: data\ui\flags\netherlands_republic
      is_ally: boolean: true
    5: table
      faction_colour: table
        b: number: 0.0039215688593686
        g: number: 0.85098046064377
        r: number: 0.99215692281723
      history: table
        1: table
          military: number: 5
          overall: number: 23
          enlightenment: number: 0
          naval: number: 8
          economics: number: 10
        2: table
          military: number: 5
          overall: number: 23
          enlightenment: number: 0
          naval: number: 8
          economics: number: 10
        3: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        4: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        5: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        6: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
      name: string: Spain
      is_enemy: boolean: false
      is_neighbouring: boolean: false
      key: string: spain
      flag_path: string: data\ui\flags\spain
      is_ally: boolean: false
    6: table
      faction_colour: table
        b: number: 0.32549020648003
        g: number: 0.19215688109398
        r: number: 0
      history: table
        1: table
          military: number: 16
          overall: number: 16
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        2: table
          military: number: 16
          overall: number: 16
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        3: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        4: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        5: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        6: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
      name: string: Prussia
      is_enemy: boolean: false
      is_neighbouring: boolean: false
      key: string: prussia
      flag_path: string: data\ui\flags\prussia
      is_ally: boolean: false
    7: table
      faction_colour: table
        b: number: 0.21960785984993
        g: number: 0.18823531270027
        r: number: 0.62745100259781
      history: table
        1: table
          military: number: 10
          overall: number: 13
          enlightenment: number: 0
          naval: number: 0
          economics: number: 3
        2: table
          military: number: 10
          overall: number: 13
          enlightenment: number: 0
          naval: number: 0
          economics: number: 3
        3: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        4: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        5: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        6: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
      name: string: Poland-Lithuania
      is_enemy: boolean: false
      is_neighbouring: boolean: false
      key: string: poland_lithuania
      flag_path: string: data\ui\flags\poland_lithuania
      is_ally: boolean: false
    8: table
      faction_colour: table
        b: number: 0
        g: number: 0
        r: number: 0.52549022436142
      history: table
        1: table
          military: number: 6
          overall: number: 16
          enlightenment: number: 0
          naval: number: 0
          economics: number: 10
        2: table
          military: number: 6
          overall: number: 16
          enlightenment: number: 0
          naval: number: 0
          economics: number: 10
        3: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        4: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        5: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        6: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
      name: string: Ottoman Empire
      is_enemy: boolean: false
      is_neighbouring: boolean: false
      key: string: ottomans
      flag_path: string: data\ui\flags\ottomans
      is_ally: boolean: false
    9: table
      faction_colour: table
        b: number: 0.13333334028721
        g: number: 0.41568630933762
        r: number: 0.13333334028721
      history: table
        1: table
          military: number: 16
          overall: number: 16
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        2: table
          military: number: 16
          overall: number: 16
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        3: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        4: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        5: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        6: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
      name: string: Russia
      is_enemy: boolean: false
      is_neighbouring: boolean: false
      key: string: russia
      flag_path: string: data\ui\flags\russia
      is_ally: boolean: false
    10: table
      faction_colour: table
        b: number: 0.60000002384186
        g: number: 0.35686275362968
        r: number: 0.05882353335619
      history: table
        1: table
          military: number: 11
          overall: number: 12
          enlightenment: number: 0
          naval: number: 1
          economics: number: 0
        2: table
          military: number: 11
          overall: number: 12
          enlightenment: number: 0
          naval: number: 1
          economics: number: 0
        3: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        4: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        5: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        6: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
      name: string: Sweden
      is_enemy: boolean: false
      is_neighbouring: boolean: false
      key: string: sweden
      flag_path: string: data\ui\flags\sweden
      is_ally: boolean: false
    11: table
      faction_colour: table
        b: number: 0.10980392992496
        g: number: 0.41960787773132
        r: number: 0.70980393886566
      history: table
        1: table
          military: number: 7
          overall: number: 7
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        2: table
          military: number: 7
          overall: number: 7
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        3: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        4: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        5: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        6: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
      name: string: Maratha Confederacy
      is_enemy: boolean: false
      is_neighbouring: boolean: false
      key: string: maratha
      flag_path: string: data\ui\flags\maratha
      is_ally: boolean: false
    12: table
      faction_colour: table
        b: number: 0.10588236153126
        g: number: 0.41960787773132
        r: number: 0.37647062540054
      history: table
        1: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        2: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        3: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        4: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        5: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
        6: table
          military: number: 0
          overall: number: 0
          enlightenment: number: 0
          naval: number: 0
          economics: number: 0
      name: string: Mughal Empire
      is_enemy: boolean: false
      is_neighbouring: boolean: false
      key: string: mughal
      flag_path: string: data\ui\flags\mughal
      is_ally: boolean: false