Mods

From BronzeWiki
Jump to: navigation, search

Bronze Age supports mods altering graphics, data, and script logic. Mods can be installed by dropping zip files into the mods directory, then enabling them through the Mods menu, available from the main menu.

Mods Menu[edit]

The Graphics Mods menu shows a list of currently loaded mods, allowing you to select and activate them. The name, author, and description of the selected mod is also shown. The "Open Mod Folder" button will open the graphics mod folder in windows explorer, allowing you to easy drag in new mods. After adding new mods, use "Refresh List" to update the mod list. The game will remember activated mods between sessions.

When a mod is enabled you can change its position in the load order. This may be important for mods that change the same files, mods loaded later will overwrite any files changed by mods loaded earlier.

"Apply" will quickly restart the game to load the selected mods.

Creating a Mod[edit]

Mods are easy to create, each is just zip archive containing a set of files and a manifest. If the mod contains an image called "cover.png", then that image will be displayed in the mod menu. The manifest is a simple XML file with information about the mod, for example:

   <manifest>
       <name>Example Mod</name>
       <author>Example Author</author>
       <description>This is a example description of an example mod.</description>
   </manifest>

There are some example mods distributed with Bronze Age, they can be found by opening the mod folder. At the root install directory there is a zip file called "BaseMod.zip", this is packaged identically to a mod, but it is always loaded, and is always loaded first. If you're looking for an example of how to do something in a mod, look in BaseMod, as the core gameplay data, graphics, and scripting are all in there.

Graphics Mods[edit]

To change the graphics simply create a mod that contains image files with the same names of the graphics files you want to change. When enabled, your mod will overwrite the default graphics. Look in "BaseMod.zip" to see all of the existing graphics.

Changing the font through mods is unsupported at this time.

Data Mods[edit]

The data for structures, world generation, items, and races is all specified in a set of XML files loaded through mods. Building out a full specification will take awhile, but "BaseMod.zip" has lots of examples.

Modifying Data Files[edit]

Mods can change data files instead of replacing them. There are three XML elements you can add to an xml file to your mod, these will be processed after mods are unpacked, but before data is loaded, changing the XML files themselves.

   <remove_element 
       parent_type="race" parent_id_attribute="id" parent_id_value="race_human" 
       target_type="available_structure" target_id_attribute="id" target_id_value="human_tower_0"/>

This will remove an element from the data file. This example will remove <available_structure id="human_tower_0" /> from h_r_human.xml (which removes towers from the human race). parent_type, parent_id_attribute, and parent_id_value all identify the element containing the element to remove. target_type, target_id_attribute, and target_id_value, identify the element to remove. So, the above will:

Find an element in the XML file named "race", that has an attribute "id" that has the value "race_human", then remove all of its children that are named "available_structure", with an attribute "id" that has the value "available_structure".

   <add_element parent_type="race" parent_id_attribute="id" parent_id_value="race_human">
       <available_structure id="maskling_ratpen" />
   </add_element>

This adds an element. Like remove_element above, parent_type, parent_id_attribute, and parent_id_value all determine what element will be targeted, if a target is found, the contents of the "add_element" element, will be added to the target. This example adds <available_structure id="maskling_ratpen" /> to the human race definition, which gives humans the ability to build maskling ratpens.

   <set_attribute parent_type="race" parent_id_attribute="id" parent_id_value="race_maskling"
            attribute="player_available" value="true"/>

The last element changes an attribute value (or adds an attribute with a value). Like the other two, parent_type, parent_id_attribute, and parent_id_value determine the target. attribute is the name of the attribute to change, and value is the value the attribute should have. This example will change the "player_available" attribute to "true" for the maskling race, which makes the race available to pick when starting a new game.

TestMod, which is distributed with Bronze Age has an example of these new data modifiers.

Script Mods[edit]

Bronze Age supports scripting through javascript. AI and events are all run through scripts.

You can download the current Script API, which can be used as a definition file for TypeScript, or as a manual reference.


Triggers[edit]

Triggers are created with a function that will be executed every update (roughly 60 times a second). Their intended use is to create events. BaseMod contains an example trigger in "t_migrants.js". This trigger periodically checks the player's population and starts a migrants event. Triggers are created by calling "addTrigger" on script load. Triggers two "property bags" (NumberProperties and StringPropterties) that are persisted through save and load, as long as the name of the trigger doesn't change. You can add any named property to them.

    var trigger = addTrigger("triggerName", "updateFunctionName");
    
    trigger.StringProperties["any name will do"] = "value to save";
    
    function updateFunctionName(trigger)
    {
        // This will be called every update, with the trigger as a parameter
    }

Events[edit]

Events are similar to Triggers, but they don't have to be recreated at script load. Any running events will be loaded with a saved game. Like triggers they have a function that will be executed every update (roughly 60 times a second), like Triggers they also have two "property bags" for saving data. Unlike Triggers, Events can expire. By setting IsExpired to true on an event it will be removed from the game at the end of the update cycle. Events can trigger notifications visible to the player through the addMessageNotification or addQuestionNotification functions. The former just displays a message, while the latter offers the player a choice.

    var event = addEvent("eventName", "eventUpdateFunction");
    event.StringProperties["any name will do"] = "value to save";
    function eventUpdateFunction(event)
    {
        // This will be called every update, with the event as a parameter
        addMessageNotification(
            "Message Title",
            "This is the body of the messsage",
            "imageNameForIcon",
            "soundNameToPlay", // modding sounds is currently not supported, "ui_notification_minor" is a good default
            20, // how long the message will last
            "functionNameForWhenTheNotificationIsClosed", // this can also be empty
            event);
        event.IsExpired = true; // remove the event
    }

AI[edit]

To Do

Script Console[edit]

The script console is accessible by pressing the tilde (~) key. This is an interactive script console, and you can enter any script command, for it to be executed immediately. All log statements will printed to this console. The normal mod API commands are all available, as are any functions added by loaded mods.


List of Mods[edit]

  • DevMode Mod - A simple mod that sets a debug flag for development. Distributed with Bronze Age.
  • Test Mod - An example of a simple mod that replaces the title graphics. Distributed with Bronze Age.


List of 1.4 Mods[edit]

Mods for 1.4 were limited to just modifying the stock graphics.

  • ASCII Mod - An example graphics mod that replaces everything with ASCII. Distributed with Bronze Age.
  • Art Pass Mod - An unreleased SNES styled art pack by Harry.