Results 1 to 30 of 102

Thread: A Beginner's Guide to Scripting & Scripting "How To"s

Hybrid View

Previous Post Previous Post   Next Post Next Post
  1. #1

    Default A Beginner's Guide to Scripting & Scripting "How To"s

    This guide was developed from the research of several members of the modding community. The research thread can be found here

    A BEGINNER'S GUIDE TO SCRIPTING

    Scripting allows modders a way of changing the game’s mechanics in ways that are impossible by other means.

    What is a script?
    A script is simply a text file that contains series of commands, similar to those that can be entered into the RomeShell console.

    There are two types of script, referred to as Campaign scripts and Show Me scripts.

    Campaign scripts are scripts that are launched at the very beginning of a new campaign – the most famous example (and indeed the only one provided in the original game) is the Prologue script which runs throughout most of the Sons of Mars prologue campaign and controls much of the automated activity within it.

    Show Me scripts are scripts that are activated by the player through the ‘Show Me How’ button on the advisor interface. They were intended to be used to help demonstrate how to do certain actions within the game, but they will run any script and can be used for the modder’s own evil purposes *bwa*ha*ha*ha*

    Due to limitations on Campaign scripts (they only activate at the start of campaigns and you can’t save while one is running) they have only a few uses to the modder and so by far the most common kind of modded script is the Show Me script.

    The most significant limitation on the Show Me script is that they can’t be run without the player’s consent (ie, if they don’t click on the show me how button then the script will never be run). But then why the hell are they playing a scripted mod if they’re not prepared to run the scripts in the first place?

    In this guide, however, we’re going to walk-through a simple Show Me script (the Mo Money script) in order to familiarise ourselves with a script’s components and terminology.

    Components of a Show Me script
    A Show Me script is just a text file contained within the data\scripts\show_me\ folder, however to implement a script other components are required:
    - a Trigger – contained within export_descr_advice.txt
    - an Advice Thread – also contained within export_descr_advice.txt
    - a Script – a text file itself contained within data\scripts\show_me\ folder

    The Trigger tells the game what actions or events it should be looking for evaluating whether the advisor should appear.

    The Advice Thread is a control which sets the number of times a trigger can be activated and other criteria before the advisor appears.

    The Script is the series of commands which are run when the player clicks on the ‘show me how’ button in the advisor’s window.

    For this example we’re going to work forwards through these steps, just to illustrate the process flow. When you actually come to making your own scripts it may be easier to work backwards or forwards through the steps.

    Step One – The Trigger
    The triggers are contained within the bottom section of export_descr_advice.txt. There you’ll find the 1,019 triggers that come with the basic game. Most of these are entirely useless to us and so we often have to define our own. In this case, however, we’ll be using a trigger that’s already there.
    Code:
     ;------------------------------------------
    Trigger 2137_Help_Campaign_Keyboard_Shortcuts_Scroll_Trigger
        WhenToTest ScrollAdviceRequested
    
        Condition ScrollAdviceRequested help_scroll
    
        AdviceThread Help_Campaign_Keyboard_Shortcuts_Scroll_Thread  0
    This is just for your information at the moment; no adjustments need to be made as the trigger already exists. We’ll get into the technicalities of what the individual lines mean on another occasion. Suffice it to say that it should be obvious that this trigger is activated when the player clicks on the request advice button on the Help Scroll (otherwise known as the Keyboard Shortcuts scroll). This scroll can be accessed simply by pressing F1 during the game.

    Trigger 2137 is very useful for testing out other components because it is slightly tucked away and therefore unlikely to be clicked during the course of play and it is completely within the player’s control. Press the request advice button once and the trigger will be activated once – so a modder can tell if the other components are working properly.

    Step Two – The Advice Thread
    The advice threads are contained within the top section of export_descr_advice.txt. They provide the connection between the trigger and the script that we want to run and determine whether the activation of a trigger actually results in the appearance of the advisor.

    This is the normal version of the advice thread that is connected to Trigger 2137
    Code:
     ;------------------------------------------
    AdviceThread Help_Campaign_Keyboard_Shortcuts_Scroll_Thread
        GameArea Campaign
    
        Item Help_Campaign_Keyboard_Shortcuts_Scroll_Text_01
            Uninhibitable
            Verbosity  0 
            Threshold  1 
            Attitude Normal
            Presentation Default
            Title Help_Campaign_Keyboard_Shortcuts_Scroll_Text_01_Title
            Text Help_Campaign_Keyboard_Shortcuts_Scroll_Text_01_Text1
    Again, we’ll have a look at this line-by-line on another occasion. The significant things to note here are the Advice Thread line at the top – which is how this Advice Thread is linked to the Trigger and also the Title and Text lines at the bottom which are refer to blurb contained with export_descr_advice_enums.txt.

    But at the moment this advice contains no reference to a script and therefore we are going to have to add one.

    This is the new version:
    Code:
     ;------------------------------------------
    AdviceThread Help_Campaign_Keyboard_Shortcuts_Scroll_Thread
        GameArea Campaign
    
        Item Help_Campaign_Keyboard_Shortcuts_Scroll_Text_01
            Uninhibitable
            Verbosity  0 
            Threshold  1 
            Attitude Normal
            Presentation Default
            Title Help_Campaign_Keyboard_Shortcuts_Scroll_Text_01_Title
            Script scripts\show_me\mo_money.txt
            Text Help_Campaign_Keyboard_Shortcuts_Scroll_Text_01_Text1
    The only line we’ve added is the one that begins Script and this refers to our script text file that we are just about to place in the show_me folder.

    Step Three – The Script
    Create a new text file within data\scripts\show_me\ and copy and paste the following into it.
    Code:
    script
    	console_command add_money 1000
    	campaign_wait 5
    	console_command add_money 1000
    end_script
    Then save the file as mo_money.txt
    In case it’s not obvious, when activated this script adds 1,000 denarii to the player’s treasury, will wait for 5 seconds and then add another 1,000. Big whoop, but it does make it easy to tell when the script has been activated and so again is useful for testing other components.

    Congratulations, you have now installed your first script. Launch a campaign as normal, then press F1 to get to the keyboard shortcuts scroll, click on Request Advice and the advisor should appear. Click on the ‘show me how’ button and the script should run as described.

    NB - the full parameter for the add_money command is:
    Code:
    add_money (opt:faction) (amount)
    so you can also specify which faction gets the money if you wanted to make it a reward for a mission (similar to a senate mission) or to represent a general time of prosperity or donations from clients or allies in times of distress.

    More Scripting How tos
    How to: Toggle Perfect Spy
    How to: Create units ~ including unique units
    How to: Capture Settlements
    How to: Create Buildings
    How to: Change the Date
    How to: Spawn an Army



    Scripting links
    Events, Conditions & Commands - this is a list of all the Identifiers, Conditions and Events from files included in the RTW demo
    Research: Parameters for commands & console commands - an attempt to compile a definitive list of command parameters
    Console commands & command line options - this is a list of many possible console commands some of which can be used through scripting
    Scripting research thread
    Hot Seat Mod - Beta Release
    More than two turns a year - release
    Client Kingdoms expansion mod
    Last edited by Epistolary Richard; 09-23-2005 at 22:42.
    Epistolary Richard's modding Rules of Cool
    Cool modders make their mods with the :mod command line switch
    If they don't, then Cool mod-users use the Mod Enabler (JSGME)
    Cool modders use show_err
    Cool modders use the tutorials database Cool modders check out the Welcome to the Modding Forums! thread Cool modders keep backups Cool modders help each other out

  2. #2

    Default How to: Toggle Perfect Spy

    How to: Toggle Perfect Spy

    toggle_perfect_spy was one of those frustrating commands that we were told could be used through the RomeShell console but it turned out that we couldn't.

    Fortunately it runs perfectly well from a script. Use the below in place of the mo_money script in Step Three above.

    perfect_spy.txt
    Code:
    script
    	console_command toggle_perfect_spy
    end_script
    This command is of great use to modders who want to observe how the AI is reacting to their changes. toggle_perfect_spy allows you to look inside each banner and settlement and look at the troop composition and characters therein. It is best used with the toggle_fow RomeShell command which lifts the shroud from the campaign map.
    Epistolary Richard's modding Rules of Cool
    Cool modders make their mods with the :mod command line switch
    If they don't, then Cool mod-users use the Mod Enabler (JSGME)
    Cool modders use show_err
    Cool modders use the tutorials database Cool modders check out the Welcome to the Modding Forums! thread Cool modders keep backups Cool modders help each other out

  3. #3

    Default How to: Create units ~ including unique units

    How to: Create units ~ including unique units

    The Client Kingdoms mod uses this in order to generate the troops the player is offered though there are many, many other uses.

    Here's a sample script:
    Code:
    script
    console_command create_unit Campus_Scythii "barb infantry briton" 4
    end_script
    In this case when the script is activated 4 units of the Briton Warband will be created in Campus Scythii.

    It need not necessarily be a settlement, you can also use a character name. This example comes from the Prologue script.

    Code:
    script
    console_command create_unit "Gaius Julius" "roman velite" 2
    end_script
    RomeShell provide these parameters:
    Code:
    create_unit (settlement/character_name) (unit_id) (opt: how many)(opt: exp/armour/weapon)
    Here's the relevant points
    - the troop description corresponds to their Type line in export_descr_unit
    - character names must be in "quotes", settlements not
    - double or triple-barrelled settlement names must have an _ instead of spaces
    - importantly, the troops become owned by whoever controls the settlement or the character's faction, there is no need for a faction to be able to build the unit or even have ownership in export_descr_unit.

    This gives us the potential to have unique units appear not just at the beginning of the game but also as it progresses as you can trigger this script based on date, the capture of a particular settlement, the construction of a building or anything else specified amongst the event identifiers.

    And as no changes are needed to export_descr_unit it means that custom battles and bribery are completely unchanged.
    Epistolary Richard's modding Rules of Cool
    Cool modders make their mods with the :mod command line switch
    If they don't, then Cool mod-users use the Mod Enabler (JSGME)
    Cool modders use show_err
    Cool modders use the tutorials database Cool modders check out the Welcome to the Modding Forums! thread Cool modders keep backups Cool modders help each other out

  4. #4

    Default How to: Capture Settlements

    How to: Capture Settlements

    This script ousts whatever garrison is in the settlement and gives it to the local faction (ie, the player's faction)

    Code:
    script
    console_command capture_settlement Londinium
    end_script
    It can be used in conjunction with the create_unit command to provide an instant garrison loyal to the player, or equally with a negative add_money that would represent the player purchasing the settlement or sponsoring an uprising.

    Because this command only gives the settlement to the player, it can't be used on the player's own settlements.
    Epistolary Richard's modding Rules of Cool
    Cool modders make their mods with the :mod command line switch
    If they don't, then Cool mod-users use the Mod Enabler (JSGME)
    Cool modders use show_err
    Cool modders use the tutorials database Cool modders check out the Welcome to the Modding Forums! thread Cool modders keep backups Cool modders help each other out

  5. #5

    Default How to: Create Buildings

    How to: Create Buildings


    Code:
    script
    console_command create_building Londinium muster_field
    end_script
    The building name is referenced from the entry export_descr_buildings.

    There are no limitations on which buildings can be given to which faction - even buildings which aren't normally available (such as Royal Barracks or Amphitheatres for the Britons). You can even have duplicate buildings.

    Combined with a date trigger, this allows you to build a unique building at a specific time in the game and therefore could be used for "Wonder"-like buildings.
    Epistolary Richard's modding Rules of Cool
    Cool modders make their mods with the :mod command line switch
    If they don't, then Cool mod-users use the Mod Enabler (JSGME)
    Cool modders use show_err
    Cool modders use the tutorials database Cool modders check out the Welcome to the Modding Forums! thread Cool modders keep backups Cool modders help each other out

  6. #6
    Member Member Jason's Avatar
    Join Date
    May 2005
    Location
    Ft. Worth, Texas
    Posts
    30

    Default Re: A Beginner's Guide to Scripting & Scripting "How To"s

    Ok please pardon my newbishness but I have never done a mod before and I am trying out what you have outlined here in this thread.

    This btw was a very well written thread and I found it very easy to understand with only one problem. It doesnt appear to work for me. Im not sure why.

    I have no other mods on my system, just the vanilla game, with patch 1.2 installed.

    Now as far as I can tell the problem resides in the line:

    Script scripts\show_me\mo_money.txt

    that is put in the advicethread portion of the file export_descr_advice.


    When I install this line in the file and then save, Rome will start up, show me the first Activision screen and then promptly crash to desktop.

    When I take the line out and save it plays as normal.

    I have been over the lines very carefully in an attempt to spot any typos or other stupid things that might have caused the problem and as far as I can tell I have followed your directions to the letter (litterally).

    I have even gone so far as to compare my line with other Script lines in other advicethread sections to see if I messed up my syntax somewhere but to no avail.


Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •  
Single Sign On provided by vBSSO