Compatibility

DAO has an active modding community. Over time, players will accumulate many new campaigns and game mods. So, as a courtesy to players and other builders, it's helpful to try to make our mods mutually compatible.

From time to time, Bioware may well issue new releases, so it's good to reduce the risk of conflict in that respect, too.

Since we can't be sure that all authors will respect compatibility considerations, the emphasis here is on techniques that reduce the risk of conflict, regardless of what other people do (though not all are foolproof).

Obviously, there are some conflicts with no win-win (hurlocks can't be both green and purple at the same time), but that doesn't stop us trying to avoid unnecessary win-lose or corruption.

Disable Add-Ins : Suggested Disclaimer

If the player disables all other add-ins on the in game DLC screen, no conflict should occur between them. Tedious, but effective.

This should rarely be necessary if the compatibility guidelines listed here are observed.

Exception : there is a toolset bug which produces content that persists in game, even when the add-in is disabled, unless the builder cleans it out before making the Builder-to-Player file. The same problem can occur if a builder has intentionally placed content in the packages\override folder (which should normally be avoided, as it is very rarely necessary).

Mod authors can work together to set player expectations in this respect. For example, the installation instructions might say

Reasonable steps have been taken to make this mod compatible. 
Obviously, the author has no control over the quality of other mods you may have installed. 
So, to reduce the risk of conflict, you are are strongly advised to move all files out of your 
packages\override folders, and consider disabling unnecessary community mods on your in-game 
DLC screen, before playing.

Module Scope

Setting the Extended Module in Module properties to "Core Game Resources" means that the add-in will change every campaign in game. If that's not intended, select the campaign you're trying to extend e.g. Single Player for the official campaign, (None) for a new standalone campaign.

What if my mod extends both Single Player and Awakening?

Resource Scope

The Owner Module resource property has a similar effect on individual design resources. It's easy to make a new core resource accidentally when copy-editing an official core resource, because the Owner Module defaults to core. This isn't obvious, but the resource will export to your module's core folder, where it will impact every campaign in game.

Normally, it's not a good idea to make new core resources.

Exception : items cannot be imported to a new campaign with the player character unless the template is included in both campaigns. One way of doing that is to make it a core resource - but that affects all campaigns, of course.

Placing resources in the packages folder should be avoided (unless you have a very good reason), because once a player has installed those resources, they persist, even when your add-in is disabled.

Unfortunately, the packages folder has to be used for resources that won't load from the addins folder, namely

• Tintmaps
• Resources which are required for the standalone Character Creator program

Art resources posted to local are always sent to the module's core folder.

Resource Conflict

Resource names need to be unique within type. For example, genpt_party.plt and genpt_party.nss are different resources, becasue the type is different. However, if two modules both have resources called genpt_party.plt, only one will load in game, following the Source directory priorities.

Within the toolset database, duplicate resource names are forbidden, but there's nothing to stop different builders making resources which accidentally conflict, so it's wise to choose a unique range of names. Each builder can register the prefix they require. See Resource Naming Convention and especially Prefixes in use.

It is possible to override a core resource intentionally, by editing a copy, exporting it, and renaming it in the export folder to the same name as the original. However, almost invariably there is a cleaner way of doing this - for example, by changing the 2DA which identifies which resource to use.

2DA Conflict

Conflict between 2DA mods can be reduced using the M2DA mechanism and reserving ID ranges.

2DA mods should normally be placed in the add-in's module folder. Exception : if they are meant to be universally applied to all campaigns, they should be in the addin/core/override folder. The packages override folder should normally be avoided (because that removes control from the player, by forcing the 2DA to load even if the player has disabled the add-in).

String Conflict

When a new module is created, its properties include a String ID range which starts at a very large random number. This makes it very unlikely that text created by one add-in will override another.

See String ID main article for a discussion of how this impacts sharing between Builders.

Event Handling Conflict

Bear in mind that an add-in which impacts all campaigns could have undesirable consequences if it changes scripts or event-handling, given that custom campaigns may well have made changes of their own. If in doubt, consider modding the Single Player campaign only.

See event override for recommended methods of intercepting events.

Note that script resources are never overwritten in these methods. Conceptually, the event is intercepted by a custom script, then passed on (unless the event has been handled successfully and further processing would be harmful). In this way, mods try not to interfere unnecessarily with other scripts.

Given the variety of actions that can be taken in a script, and that fact that one mod can't know what other mods are trying to do, we can't guarantee that this approach will be entirely free of logical problems, but the Perfect is the enemy of the Good.

The simplest and safest method is to assign a custom event script to a resource. This is likely to be used by custom campaigns, and also by Single Player mods to specific resources, as it is the approach that Bioware devs have often recommended.

Mods which aim to impact all campaigns globally are better advised to use the second method, i.e. overriding event handling using an Events M2DA. As illustrated in the example script, if possible the event should be passed on to the default handler of the event's target object (which might be a custom event script). In this way, a global mod can be compatible with custom campaigns and specific resource mods.

Unfortunately, if two mods simply try to override the same event with an M2DA, they will be incompatible.

The best solution to override, partially override, or just listen for events via M2DA at this point would be to use a system such as Event Manager, though to ensure compatibility all modules overriding or listening for events should also be using the same system.

In the case of modules trying to totally override an event, only one module that does so will ultimately "win" (no such modules can ever truly be compatible with one another short of merging their functionality into one unified module as possible), but utilizing a system such as Event Manager will allow modules to partially override an event (i.e. only handle the event in certain situations), and will allow any module to listen for an event (without handling it) before or after the event is handled.

Plot Property

Scripts that impact all campaigns should respect the plot property on resources. For example, if a campaign author has flagged an NPC as plot, it might not be helpful to change the creature AI.

Open Source

If mod authors choose to publish their source code, with no restrictions on re-deployment, other builders can work around any residual incompatibilities (either by understanding the conflict more clearly, or by integrating the mod into their own work).

This technical wiki is not the place to discuss any legal or ethical considerations.

FAQ

What if my mod extends both Single Player and Awakening?

Just create two dazips for your module. Name one yourprefix_yourmodule_version and the other yourprefix_yourmodule_EP1_version.

Edit the Manifest.xml file inside yourprefix_yourmodule_EP_1_version.dazip. Change the line

<AddInItem UID="yourprefix_yourmodule" Name="Your Module Name" ExtendedModuleUID="Single Player" Priority="100" Enabled="1" State="2" Format="1"> to

<AddInItem UID="yourprefix_yourmodule_EP_1" Name="Your Module Name" ExtendedModuleUID="DAO_PRC_EP_1" Priority="200" Enabled="1" State="2" Format="1">

See also Talk:Compatibility Discussion

===

NOTE:

There is an easier way than creating two scripts. Just put the information for both in the manifest.xml file. For one of my mods, the manifest file looked like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Manifest Type="AddIn">
	<AddInsList>
		<AddInItem UID="elf_cat_pet" Name="ELF the pet cat for DAO and Awakening" ExtendedModuleUID="Single Player" Priority="100" Enabled="1" State="2" Format="1">
			<Title DefaultText="ELF the pet cat for DAO and Awakening"></Title>
			<Description DefaultText="ELF the pet cat adds a 'Cat Toy' to the players inventory (rest of text deleted for brevity)

((This package will work in both DAO and Awakening!))"></Description>
			<Image>ico_elf_cat_sleep</Image>
			<Rating DefaultText="10"></Rating>
			<RatingDescription DefaultText=""></RatingDescription>
			<URL DefaultText="www.ELFpath.com"></URL>
			<ReleaseDate>6 April 2010</ReleaseDate>
			<Version>2.0</Version>
			<GameVersion/>
			<Type>1</Type>
			<Publisher DefaultText="Angel == monkeysnest@yahoo.com"></Publisher>
			<PrereqList/>
			<FileList>
				<Folder src="packages/" Type="package"/>
				<Folder src="addins/" Type="addin"/>
			</FileList>
		</AddInItem>

		<AddInItem UID="elf_cat_pet" Name="ELF the pet cat for DAO and Awakening" ExtendedModuleUID="DAO_PRC_EP_1" Priority="100" Enabled="1" State="2" Format="1">
			<Title DefaultText="ELF the pet cat"></Title>
			<Image>ico_elf_cat_sleep</Image>
			<Rating DefaultText=""></Rating>
			<RatingDescription DefaultText=""></RatingDescription>
			<URL DefaultText="www.ELFpath.com"></URL>
			<ReleaseDate>6 April 2010</ReleaseDate>
			<Version>2.0</Version>
			<GameVersion/>
			<Type>1</Type>
			<Publisher DefaultText="Angel == monkeysnest@yahoo.com"></Publisher>
			<PrereqList/>
			<FileList>
				<Folder src="addins/" Type="addin"/>
			</FileList>
		</AddInItem>

	</AddInsList>
</Manifest>

doing this allowed users to install one package (using DAModder) which worked for both awakening and DAO.

============== ++ Angel

How can I import an item with my existing character to a new campaign?

The Awakening expansion allows an existing character to be imported from one campaign to another.

There are two methods of ensuring that an item in the player's inventory is imported successfully:

• Make the item a core resource
• Include the item template in separate add-ins to both campaigns (see Awakening example above)

How can I stop items being imported into my campaign?

Assuming your campaign allows existing characters to be imported during Character Generation, you might want to clear the player's inventory before adding your starting equipment. Imported equipment might upset the balance of your campaign.

If you decide to do this, it's a good idea to warn players, so that they understand what's happening.