Modding:Encounters and Population

From Caves of Qud Wiki
Revision as of 00:32, 22 December 2020 by Egocarib (talk | contribs) (Add new info about population table merging)
Jump to navigation Jump to search
This page is about modding. See the modding overview for an abstract on modding.
This page is about modding. See the modding overview for an abstract on modding.

There are two primary population systems in Caves of Qud, the legacy EncounterTables.xml system, and the ZoneTemplates.xml+PopulationTables.xml system. Encounter tables are an older system and we prefer to use zone templates + population tables these days, but much of the game is still populated via EncounterTables.xml.

Like ObjectBlueprints.xml, both the EncounterTables.xml and the PopulationTables.xml support use of the Load="Merge" attribute to merge content into existing tables defined by the base game files. This will append entries to the specified table instead of overwriting it.

Many zone template encounters draw objects from dynamically created population tables. Check out the following tags in ObjectBlueprints.xml to see them in use: DynamicObjectsTable, ExcludeFromDynamicEncounters. Some dynamic population tables are created based on the base type of the object, so new objects will begin appearing immediately in areas generated with dynamic population tables unless they are tagged with ExcludeFromDynamicEncounters. Refer to the section below for more information about Dynamic population tables.

The unaffiliated cave systems are one area that is heavily populated with the zone template+population system.

Extending Encounter Tables

You may add new entries to existing encounter tables by including EncounterTables.xml in your mod, using an existing table name and setting the Load="Merge" property on the encountertable tag.

Adding "My New Ammo" to the "Ammo 1" built-in encounter table

<encountertables>
  <encountertable Name="Ammo 1" Load="Merge">
    <objects>
      <object Chance="100" Number="3d6" Blueprint="My New Ammo"></object>
    </objects>
  </encountertable>
</encountertables>

Extending Population Tables

To modify existing populations, you can take a similar approach. For example, the following could be used in a mod's PopulationTables.xml file to add a new type of Wristblade Legendary merchant lair:

  <population Name="GenericLairOwner" Load="Merge">
    <group Name="Options" Load="Merge">  <!-- Add the Load="Merge" attribute to each nested group, mimicking the base game's PopulationTables.xml structure -->
      <object Blueprint="WristbladeMerchant" Weight="20" /> <!-- Insert your new item! -->
    </group>
  </population>

Of course, this would also need to be supplemented with an ObjectBlueprints.xml that defines the new "WristbladeMerchant". It would likely inherit from "BaseMerchant" and have the appropriate parts defined, similar to other legendary merchants.

Full Example Usage

Here is some example XML from a mod that creates a fully functional Six Day Stilt vendor using a combination of Load="Merge" tables and new tables defined by the mod. This is everything that's needed in the mod's PopulationTables.xml file, though this won't work by itself. It would also require an ObjectBlueprints.xml to define the various Blueprint objects that are not included here.

  <!-- Merge new YoyoWinderTent into the game's StiltTents population table -->
  <population Name="StiltTents" Load="Merge">
    <group Name="Types" Load="Merge">
      <table Name="YoyoWinderTent" Weight="4" />
    </group>
  </population>

  <!-- Define the YoyoWinderTent -->
  <population Name="YoyoWinderTent">
    <group Name="Contents" Style="pickeach">
      <object Blueprint="YoyoWinder" Number="1" Hint="Interior" />
      <table Name="YoyoWinderTentContents" />
    </group>
  </population>
  <population Name="YoyoSigns">
    <group Name="Items" Style="pickone">
      <object Blueprint="YoyoSign1" Number="1" Hint="OutsideDoor:1" />
      <object Blueprint="YoyoSign2" Number="1" Hint="OutsideDoor:1" />
      <object Blueprint="YoyoSign3" Number="1" Hint="OutsideDoor:1" />
    </group>
  </population>
  <population Name="YoyoWinderTentContents">
    <group Name="Contents" Style="pickeach">
      <object Blueprint="Torchpost" Number="1" Hint="InsideCorner" />
      <table Name="YoyoSigns" />
      <object Blueprint="Torchpost" Number="1-2" Hint="OutsideDoor:2" />
      <object Blueprint="YoyoWinder Workbench" Number="1-2" Hint="AlongInsideWall" />
      <object Blueprint="Woven Basket" Number="1" />
      <object Blueprint="YoyoWinder Workbench" Number="1" />
      <object Blueprint="Yoyo Oil Pitcher" Number="1-2" Hint="AlongInsideWall" />
      <object Blueprint="Yoyo String Plastifer 3" Number="1" Chance="15" />
      <object Blueprint="Yoyo String Elastyne 3" Number="1" Chance="35" />
      <object Blueprint="Yoyo String Elastyne 5" Number="1" Chance="20" />
      <object Blueprint="Chest" Number="1-2" Hint="AlongInsideWall" />
    </group>
  </population>

Dynamic Tables

The game sometimes uses dynamically generated population tables, which are constructed from objects in ObjectBlueprints.xml.

For example, XRL.World.Parts.PsionicDervish may select an object from the DynamicInheritsTable:BaseLongBlade:Tier5, DynamicInheritsTable:BaseLongBlade:Tier7, or DynamicInheritsTable:BaseLongBlade:Tier9 tables depending on the type of dervish. This table will select any item that inherits from "BaseLongBlade" as long as it does not have the ExcludeFromDynamicEncounters tag. For dynamic tables of this type with a tier, the game will strongly weight items of the specified tier, but items of other tiers can also be selected.

For example, DynamicInheritsTable:BaseLongBlade:Tier5 will give a weight of 1000 to items of the specified tier, a weight of 100 to items one tier above or below that, a weight of 10 to items two tiers above or below that, and a weight of 1 to all other items. This results in a population table being constructed by the game similar to the following:

Item Weight
bronze long sword 1
bronze two-handed sword 1
iron long sword 1
two-handed iron long sword 1
steel long sword 1
two-handed steel long sword 1
carbide long sword 10
two-handed carbide long sword 10
folded carbide long sword 100
two-handed folded carbide long sword 100
fullerite long sword 1000
two-handed fullerite long sword 1000
crysteel long sword 100
crysteel great sword 100
flawless crysteel long sword 10
flawless crysteel great sword 10
zetachrome long sword 1
two-handed zetachrome long sword 1
vibro blade 1000

Additional Info

This article may need cleanup to meet quality standards.
Please help improve this page by editing it.

Reason: "The information from the Steam thread needs to be integrated into this article."

This article may need cleanup to meet quality standards.
Please help improve this page by editing it.

Reason: "The information from the Steam thread needs to be integrated into this article."

Here's a thread on Steam where Brian discusses using encounter and population tables: http://steamcommunity.com/app/333640/discussions/3/358415738194955181/