Content Generation Overview

You can create new Items of various types - Valuables, Consumables, Weapons, Armor, Accessories, and Offhands (books, quivers, shields, etc.) Items are loaded from XML files upon starting the game. Thus, to create new items, you will be writing XML. Thankfully, it's pretty easy, and you can do it with any text editor like Notepad++, Textpad, or SublimeText!

(It's also possible to create Gear Sets and set items - we'll get to that later.)

Items you create will be added to the game's loot tables automatically. You can control their challenge value (rank), relative drop rate, and whether they will be auto-added to shop tables. For finer control over shops, consider creating a shop mod as well.

Once your mod has been loaded into the game data, it's recommended that you start a new character file so that your items spawn throughout the dungeon. Do note that if you enable a mod and then disable it in a file where the mod was used, serious game errors can occur. It's best to be consistent!

XML Data Format Basics

All content data is delivered in XML files. A single file can have any number of items. Each file must be assigned to a specific type of content (see "Technical Requirements"). Each item gets its own 'block', like so:

<ACCESSORY>
	<DisplayName>My New Accessory</DisplayName>
	<RefName>accessory_myitem1</RefName>
	<Description>This is a description for my accessory.</Description>
	<SpriteRef>assorteditems_321</SpriteRef>
	<UniqueEquip>0</UniqueEquip>
	<Rank>5</Rank>
	<DropRate>100</DropRate>
</ACCESSORY>

Let's go through each line of this example.

• The top node <ACCESSORY> indicates the item type or slot.
• DisplayName is the item name shown ingame.
• RefName is the reference name used in code, but not shown to players.
• Description is self-explanatory!
• SpriteRef is the item icon. There are over 400 sprites to choose from.
• UniqueEquip is a special property for Accessories. If set to "1", only one can be equipped. If this property isn't needed, just don't include the line. We'll cover more of these later.
• Rank determines where the item can drop in the game. Lower rank items drop earlier. Max rank is 10.
• DropRate has a base weighted value of 100. Lower or increase this to change the relative chance that the item will drop.

Of course, the item above is missing any actual attributes or powers, so it isn't very useful. Since it's an Accessory, let's add an "AutoMod" node which will give it an inherent magical property. Under the DropRate line, we can add:

<AutoMod>mm_mechanist</AutoMod>

Now the item will gain the same property as the Mechanist's Talisman! For a full list of all possible magic mods, read on below.

Your XML files must also include the following text at the very top:

<?xml version="1.0" encoding="utf-8"?>

As well as an opening <DOCUMENT> tag immediately after, and a closing </DOCUMENT> at the very bottom. Here is a template file you can use to start with.

Return to Table of Contents

Technical Requirements

Your mod MUST include the following things, or it will not work in-game!

• At least one XML file adhering to the format on this page. Here is a template file you can start with.
• An image with the same exact name as your mod, formatted to 512x512 PNG. This will be used as cover art for your mod in the Steam workshop.
• A descriptions.txt file, which contains nothing but the plain text description of your mod.
• A 'manifest' where you define what each file in your mod is. The manifest should be called PlayerFileDefs.txt.

About the Manifest

This is a plain text file that tells the game what each of the mod files in your mod folder is supposed to be. It should include everything except itself and your image/art file. The manifest uses the following format.

MyFirstModFile.xml	ITEMS
MyImage.png		SPRITE
MySecondFile.xml	ITEMS

Each line of the manifest has the name of a mod file, a tab (or multiple tabs, whatever you prefer), and then the file type. The separator between the filename and mod file type MUST be an actual tab created by pressing TAB, not spacebar! There are a variety of mod file types:

• ITEMS: Any XML file that includes new or replacement item definitions.
• MONSTERS: Any XML file that includes new or replacement monster template definitions.
• SHOPS: Any XML file that includes new or replacement shop table / shop definitions.
• LOOTTABLES: Any XML file that includes new or replacement loot table definitions.
• SPAWNTABLES: Any XML file that includes new or replacement monster spawn table definitions.
• SPRITESHEET: A PNG file with multiple sprites to be used for a monster or job definition.
• SPRITESHEET_META: An XML file with animation and frame data for a spritesheet. MUST be provided if you are adding a spritesheet.
• JOBPORTRAIT: A PNG file replacing an existing character job portrait. Should be a 40x40 square with the same file name as the job (case/spaces don't matter).
• GAMEBALANCE: An XML file that adjusts various game balance elements like player damage, loot drop rate, etc.
• SPRITE: A PNG file that is referenced by your XML, such as an item sprite. Sprites should be square, with a base size of 32x32.

The manifest does NOT need to include:

• Itself
• descriptions.txt
• The mod logo PNG image (which should be the exact name of the mod)
• Steam-generated "WorkshopItemInfo.xml"

Return to Table of Contents

Mod Conflicts

There is nothing preventing you from creating and enabling as many Tangledeep mods as you'd like. However, it is worth checking that the mods aren't trying to modify the same things, otherwise some unintended behavior can occur.

The most obvious conflict can occur if using ReplaceRef to modify the same game data across multiple mods. For example, two mods alter the game data for Moss Jellies (mon_mossjelly). In this case, the replacements are executed in alphabetical order, with the last mod in the list making the final (and complete) replacement. This can happen with monsters, shops, spawn tables, loot tables, etc.

Conflicts can also arise if using multiple spritesheet replacements for the same NPC, monster, job (etc). In this case, the game will search the list of mods until it finds the first suitable replacement, and use that - meaning the FIRST mod in the list will take priority.

Make sure to read the description for each mod you're enabling to verify that there are no potential issues.

Return to Table of Contents

Universal Item Attributes

Here you will find a list all possible Attribute Nodes for Items. These are common to ALL items. Any attribute that has a value of 0 or 1 ("Boolean") need only be used if the value is "1". Otherwise, you can simply leave it out, and the game will use the default value of 0.

(Note: Boolean attributes must use the value "1" for TRUE. Do not actually type "TRUE".)

Required Universal Attribute Nodes

• DisplayName: Item name displayed ingame.
• RefName: Reference name used ingame data. Not shown ingame.
• SpriteRef: Reference name of item's ingame sprite. Can be from our palette, or your own custom sprite.
• Description: Item flavor text.
• Rank: Item rank used to calculate where the item drops. Values range 1-10.
• DropRate: Weighted drop rate of item. 100 is average. Values range 1 to 9999. By setting a DropRate, the item will be automatically added to the simplest loot table types such as Consumables, Weapons, Equipment, etc. as appropriate. You can alternatively omit this node, and modify existing loot tables with a new XML file.

Optional Universal Attribute Nodes

• ReplaceRef: Boolean. When enabled, if the RefName of this item matches an existing item in the game's core data, your content will REPLACE it. However, your item type must match the original item type. This must be placed ABOVE the RefName node.
• ExtraDescription: Field used to describe gameplay effects of item.
• ReqNewGamePlus: Boolean. When true, item will only drop in New Game Plus.
• Legendary: Boolean. When true, item is marked as Legendary. Will only drop once per character, and subject to any Legendary drop calculations / effects.
• ShopPrice: Base price of the item in shops. Also used to calculate bank deposit price.
• SalePrice: Base value of the item when YOU sell it to shopkeepers.
• NumberTag: Can be used multiple times. Each tag replaces text tags ^number1^, ^number2^ (etc) in Description fields.
• DreamItem: Boolean. When true, item disappears when exiting an Item Dream.
• AutoAddToShopTables: Boolean. When enabled, the item will show up in any shops that are high enough rank to stock the item. (Note: This does not factor in shop 'type'. For that, consider making a shop mod file.)
• AddToShopRef: Adds the item to a given ShopTable at a given weight. Should be in the format shopname,quantity. For example: <AddToShopRef>lowlevel3_general,50</AddToShopRef>

Return to Table of Contents

Shops

It's possible to create or modify shops that belong to the various town, hidden, and wandering merchants of Tangledeeps. There are two kinds of modifiable shop data: ShopTables, which are simply a list of items with spawn rates, and simply Shops, which details which tables a merchant can have, when those tables appear, value multipliers, magic item chance, etc.

For example, if you've created new items and you want to add them to existing shops, you could do this by modifying existing ShopTables and simply adding references to your new items. If you wanted to change fundamental aspects of a particular NPC's shop, you would also add their Shop as part of your mod.

However the SAFEST way to add new items to an existing shop is to use the AddToShopRef definition in your item. That lets you define the exact weight of the item in the specific ShopTable of your choice, and will NOT conflict with other mods.

(Note: Boolean attributes must use the value "1" for TRUE. Do not actually type "TRUE".)

ShopTable Nodes

• RefName: Reference name used in game data. Not shown ingame.
• ReplaceRef: Boolean. When enabled, this table will overwrite an existing table of the same name. This is what you would want to do if you are rebalancing or expanding existing tables.

Other than these two nodes, each possible item in a ShopTable follows this format, with one item per line:

<ItemName>100</ItemName>

The number defines the 'weight' of that item in the ShopTable. If a ShopTable has two items, each with 100 weight, imagine the ShopTable is a bag and 100 of each item has been added to the bag. If you add an item with a weight of only 20, then out of 220 total items, your new item will only appear 20 in 220 times.

Shop Nodes

• RefName: Reference name used in game data. Not shown ingame.
• ReplaceRef: Boolean. When enabled, if the RefName of this shop matches an existing shop in the game's core data, your content will REPLACE it.
• ShopData: Begins a new ShopData sub-node (see below). Each ShopData within a Shop defines which tables the NPC sells, at what values, number of items, and when that table is shown to the player.

ShopData Nodes

• Reference: The reference name of an existing ShopTable. This table will be used as the pool of items potentially offered.
• ValueMult: The multiplier for item prices in the shop. This affects the price the PLAYER pays, and does not affect the MERCHANT pays when buying items from the player. This can be any value from 0.01 to 999. Decimals are OK. Default is 1.0
• SellMult: Just like ValueMult, but instead multiplies the price the merchant pays for items sold BY the player.
• MinLevel: Minimum player XP level required for this ShopData to be used. Must be between 1-15.
• MaxLevel: Maximum player XP level allowed for the ShopData to be used. Must be between 1-15, and must be the same or higher than MinLevel.
• MinItems: Minimum number of items spawned in the shop when it refreshes.
• MaxItems: Maximum number of items spawned in the shop when it refreshes.
• MagicChance: Base chance of Equipment spawning with magic mods. Can be 0 to 1.0 or higher. Higher values mean higher chance of multiple magic mods.
• MaxMagicMods: Maximum possible magic mods allowed on Equipment. Can be 0 to 5.
• ChallengeValue: Base challenge value of the shop, can be between 1.0 (Rank 1) to 1.9 (Rank 10). This is used to filter items from SpecialTables (see below).
• AdaptChallengeValue: Boolean. When enabled, the ChallengeValue of the shop will rise as the player increases in level.
• ChanceToUseBaseTable: Only necessary if a shop uses SpecialTables (see below). Chance value from 0 to 1.0, where 1.0 is 100%. "BaseTable" in this case is the Reference table. Thus, this value determines the chance the shop will use the single Reference ShopTable vs. one of the SpecialTables.
• AddPossibleModFlag: Used to add a *special* MagicMod flag as possible for this shop. Special flags may not normally spawn, such as CASINO or NIGHTMARE.
• LimitModFlag: Used to restrict any Equipment magic mods to the specified flag. ONLY mods of that flag will spawn on Equipment, if any mods spawn at all. See MagicMods in the Appendices for more info.
• SpecialTables: Begins a SpecialTables sub-node. Use this to allow the shop to pull from generic loot tables not specific to shops.

SpecialTables are lists of existing loot tables, along with the weighted chance of each specific table being used. For example:

<SpecialTables>
	<equipment>100</equipment>
	<legendary>5</legendary>
</SpecialTables>

For a list of all existing shop tables and shop data, please see the reference XML file shops.xml.

For a list of all core loot tables, please see the reference XML file loottables.xml.

Return to Table of Contents

Loot Tables

You can adjust existing loot tables in Tangledeep with your own mod. Loot tables control the rate at which items are spawned in destructible objects, monster inventories, rumor rewards - anything except shop tables. You can of course create new loot tables as well, though the only way to hook up new tables to actual gameplay is via SpecialTables in shops (see above). By using the ReplaceRef flag in your XML, you could for example replace the "legendary" loot table with your own re-balanced values.

The format for LootTables are identical to ShopTables. The table is enclosed in a <LootTable></LootTable> node. It takes a RefName, a ReplaceRef flag, and then a list of items where each node is an item ref, and the contents of a node is the drop rate (as an integer: no decimals).

For a list of all core loot tables, please see the reference XML file loottables.xml. This shows exactly how you would format the tables in your own modfile.

Return to Table of Contents

Monster Spawn Tables

You can tweak and rebalance monster spawn tables in Tangledeep just like Loot Tables above. The formatting and approach is exactly the same as Loot Tables, except the top-level enclosing node is <SpawnTable></SpawnTable>.

For a list of all core spawn tables, please see the reference XML file spawntables.xml. This shows exactly how you would format the tables in your own modfile. You can also check out mapgenerator.xml to see where each spawn table is used in the per-floor map generation data.

Return to Table of Contents

Consumables

This item type includes food, potions, damage items like shurikens and darts, as well as items with no function at all except selling, such as gems.

All consumables should have some kind of power or status(es) attached. There are two ways to do this. One is the ItemPower node, which sets the ability that executes when the player actually uses the item. The other is by using one more more ItemGrantStatus nodes that will add status effects to the player on use (for example, a heal-over-time).

All other tags and flags are used for various UI and sorting purposes. They are important, but make sure to use ItemPower or ItemGrantStatus to actually set the effect!

Optional Attribute Nodes

• Food: Boolean. Marks the item as being of type 'food'. Does not grant any effects or powers on its own, but this flag is important if you actually intend the item to be food!
• HealingItem: Boolean. Marks the item as having any kind of restorative effect (directly heals Health, Stamina, and/or Energy.) Again, this does not actually grant a power by itself.
• EffectDescription