1. derakon Avatar derakon
  2. Untitled project
  3. pyrel

Wiki

Clone wiki

pyrel / data_files

View History

The data files are where most of the "content" of the game is stored. They contain the definitions for items, monsters, terrain, etc. Each file is a plaintext document in JSON format; the structure of the contents depends on the file.

This page is both the documentation so far on existing data files, and can be a thinking ground for not-yet-existing data files.

Already existing

object_affix.txt

Contains one dict entry per affix, which may contain:

  • a unique integer index (not sure this is necessary any more, as affix names are unique)
  • a name, type (make, material, quality, physical, elemental, arcane etc.), position (prefix or suffix) and genus (grouping name for use with multiple affixes) - all are single strings
  • a list of flags (RES_ACID et al.)
  • a dict of mods (these are pval flags with associated pval info)
  • a list of stats (fin/prow/ac bonuses, dice and sides, balance and heft, percentage modifiers to base AC and weight)
  • a dict of minimum stats
  • a list of affixes with which we conflict (can include self)
  • a list of procs (not implemented yet)
  • one or more dicts of allocations (commonness, min and max depths, greatness level and allowed items)

example:

    "index": 1, 
    "name": "of Resist Acid", 
    "affixType": "elemental",
    "position": "suffix", 
    "genus": "of the Elements",
    "flags": [
      "RES_ACID", 
      "IGNORE_ACID"
    ],
    "allocations": [
      {
        "commonness": 20, 
        "maxDepth": 25, 
        "minDepth": 1, 
        "itemType": {"shield": "all", "soft armor": "all", "hard armor": ["all except", "Full Plate Armor~", "Ribbed Plate Armor~"]},
        "affixLevel": "great"
      }, 
      {
        "commonness": 10, 
        "maxDepth": 50, 
        "minDepth": 26, 
        "itemType": {"shield": "all", "soft armor": "all", "hard armor": "all"},
        "affixLevel": "good"
      }, 
      {
        "commonness": 5, 
        "maxDepth": -1, 
        "minDepth": 51, 
        "itemType": {"shield": "all", "soft armor": "all", "hard armor": "all"},
        "affixLevel": "average"
      }, 
      {
        "commonness": 5, 
        "maxDepth": -1, 
        "minDepth": 45, 
        "itemType": {"crown": "all"}, 
        "affixLevel": "great"
      }
    ]

affix_meta.txt

Contains two dicts, one for affix quality levels and one for affix types. Each has one or more allocation dicts per entry, which set min and max depths and min and max numbers (of this type/level of affix). Sounds more complicated than it is:

        "bad" : {
        "rank" : 0,
        "allocations" : [
            { "minNum" : 0, "maxNum" : -1, "minDepth" : 0, "maxDepth" : 50 },
            { "minNum" : 0, "maxNum" : 2, "minDepth" : 51, "maxDepth" : -1 }]
        },

        "arcane" : {
        "allocations" : [
            { "minNum" : 0, "maxNum" : 4, "minDepth" : 0, "maxDepth" : -1 }]
        },

colors.txt

The colour table: RGB values for the defined colours (L_PURPLE and friends)

    "DARK": [0, 0, 0],
    "WHITE": [255, 255, 255],
    "SLATE": [128, 128, 128],
    "ORANGE": [255, 128, 0],

creature_template.txt

Creature templates are "incomplete" creature records. A creature can pull from the templates to establish certain common attributes, and then build on that with the creature-specific capabilities. For example, the dragon template specifies that the creature is evil, a dragon, and is represented by a 'd'.

Additionally, the player's race and class are stored here as templates that are applied on top of the player character (who is a creature like any other, except that the player controls it).

If you're coming here from Angband, then, this file roughly corresponds to monster_base.txt, p_race.txt, and p_class.txt.

Any field that appears in an entry in creature.txt can appear in this file, including templates. 

    {
        "category": "Bat", 
        "display": {
            "ascii": {
                "symbol": "b"
            }
        }, 
        "flags": [
            "ANIMAL"
        ], 
        "name": "bat", 
        "type": "bat"
    },

creature.txt

The monster.txt file, one dict per creature:

  • a unique integer index
  • a name string
  • a dict of display info
  • a list of templates it inherits
  • a dict of stats (alertness, maxhp, speed, visionRange, evasion, absorption)
  • nativeDepth, rarity, experienceValue (all integers)
  • a list of blows (each blow is a list of method, type and damage)
  • a list of flags
  • a description string N.B. No spell flags included yet 
{"index": 30, "name": "Soldier ant", 
"display": {"ascii": {"color": "L_SLATE"}}, 
"templates": ["ant"], 
"stats": {"alertness": 40, "maxHitpoints": 6, "speed": 1, "visionRange": 10}, 
"nativeDepth": 1, "rarity": 1, "experienceValue": 3, 
"blows": [["BITE", "HURT", "1d2"]], 
"description": "A large ant with powerful mandibles."},

effect.txt

At the moment this contains a few basic testing or behind-the-scenes effects (like uniqueness). It should eventually have all the info for all effects.

flavor_colors.txt

A set of dicts mapping flavours to colours by type (stones, metals, woods, liquids etc.), so that each flavour is displayed the correct colour

   {
        "type": "Textures",
        "flavors": {
            "Black Spotted": "L_DARK",
            "Furry": "L_SLATE",
            "Slimy": "SLATE",
            "Wrinkled": "UMBER",
            "White Spotted": "WHITE"
        }
    }

flavor_types.txt

A single dict mapping item types to lists of flavour types

{
    "food": ["Colors", "Textures"],
    "potion": ["Colors", "Liquids"],
    "ring": ["Stones", "Metals", "Miscellaneous"],
    "staff": ["Woods"],
    "wand": ["Metals"],
    "rod": ["Metals"],
    "amulet": ["Stones", "Miscellaneous"],
    "scroll": ["Woods"]
}

loot_template.txt

A list of dicts, each of which defines a set of rules for item generation:

  • templateName - its name, obviously
  • itemType - a dict of allowed items, keyed by type (identical to the dict format used in the "allocations" dicts in affix.txt) - values are lists of allowed subtypes but two special values are parsed separately: "all" and ["all except", "foo", "bar", "baz"]
  • itemLevel - the level at which the item is generated
  • magicLevel - the level at which affixes are generated for the item
  • numAffixes - the number of affixes generated on the item
  • minAffixLevel - the minimum quality level of affixes allowed
  • maxAffixLevel - the maximum quality of affixes allowed
  • affixType - a dict of allowed affixes, keyed by affixType (identical format to the itemType dict, with the same special parsing of "all" and "all except")
  • affixLimits - overrides for the global minima and maxima for affix types or levels
  • affixes - a list of specified affixes to be applied, not using a lookup table (these override any restrictions)
  • themeName - a specified theme to be applied, overriding any restrictions
  • themes - a list of allowed themes (can use "all except" to keep it short)
  • themeChance - an adjustment to the chance for a theme (percentage - defaults to 100, i.e. 1x usual chance)
  • artifactChance - ditto for artifact
  • itemRuleBoosts - a dict containing rules for varying any of the above numerical properties, keyed by the property name with "chance;amount" values 
 {
    "templateName": "kitchen sink",
    "itemLevel": "50+4d5M20",
    "itemType": {
        "soft armor": "all",
        "hard armor": ["all except", "Plate Mail~"],
        "shield": "all",
        "sword": "all",
        "hafted": "all",
        "polearm": "all",
        "launcher": "all" },
    "affixes": ["Brutal", "of Nightbane"],
    "magicLevel": 40,
    "numAffixes": "1+2d3M4",
    "minAffixLevel": "average",
    "maxAffixLevel": "great",
    "affixType": {
        "make": ["all except", "Orcish"],
        "material": "all",
        "quality": "all",
        "arcane": "all",
        "elemental": "all" },
    "affixLimits": {
        "levelsMin": { "average": 1, "good": 1 },
        "levelsMax": { "average": 2 },
        "typesMin": { "make": 1, "material": 1 },
        "typesMax": { "material": 2 } },
    "themeChance": 120,
    "itemRuleBoosts": {
        "itemLevel": ["50 + mapLevel;10+M5"],
        "minAffixLevel": ["20 + mapLevel;1"],
        "maxAffixLevel": ["20 + mapLevel;1"],
        "numAffixes": ["20 + mapLevel;d2"],
        "magicLevel": ["5;d60"] }
  }

object_template.txt

The equivalent of object_base.txt. Each object type is a dict containing some or all of:

  • type and templateName strings (not sure of the distinction)
  • a dict of display info
  • a list of equipSlots that the item can occupy
  • a list of stats (like weight)
  • a list of flags (like FLAVORED or HATES_FIRE) 
{"type": "boots", "templateName": "boots", 
"display": {"ascii": {"symbol": "]"}}, 
"equipSlots": ["feet"]},

object.txt

The full object info:

  • a unique integer index (necessary?)
  • type and subtype strings (these are going to change to "prefix", "name" and "suffix" - see issue #1)
  • a list of templates to inherit
  • a list of flags
  • a dict of mods (pvals)
  • a list of stats (baseArmor, dieSize, numDice etc.)
  • one or more dicts of allocations (commonness, min depth and max depth)
  • a description string
  • a list of carriedTypes of items (containers only)
  • a dict of maxCapacity (count and slots, containers only) 
{"index": 250, "subtype": "Inertia", 
"templates": "amulet", 
"mods": [{"bonus": "-d2", "flags": ["SPEED"]}], 
"flags": ["FREE_ACT", "EASY_KNOW"], 
"allocations": [{"commonness": 20, "minDepth": 15, "maxDepth": 40}]},

object_flags.txt

Details of object flags:

  • full name, capitalised label, flagType (strings)
  • ID type and ID message (strings)
  • base power rating and power multiplier (integers)
  • a dict of per-slot power multipliers 
  {
    "name": "Dexterity", 
    "powerMult": 10, 
    "basePower": 8, 
    "flagType": "STAT", 
    "label": "DEX", 
    "ID": "wield", 
    "slotPower": {
      "body": 1, 
      "head": 1, 
      "neck": 1, 
      "launcher": 1, 
      "weapon": 1, 
      "shield": 1, 
      "back": 1, 
      "feet": 1, 
      "finger": 1, 
      "hands": 2, 
      "light source": 1
    }
  }

object_theme.txt

The theme info for ego items (per v4). Contains one dict entry per theme, which may contain:

  • a unique index number (this is necessary here, as theme names derived from V are not unique)
  • strings for name and position (prefix or suffix)
  • one or more allocations dicts detailing minDepth, maxDepth and an itemType subdict of allowed items
  • a list of affixes germane to the theme, each of which is described by a dict containing a name string and weighting and chance numbers. These are lists where the affix is applied to the item more than once. 
{
    "affixes": [
      {
        "weighting": 7, 
        "chance": 100, 
        "name": "of Resist Acid"
      }, 
      {
        "weighting": 7, 
        "chance": 100, 
        "name": "of Resist Fire"
      }, 
      {
        "weighting": 7, 
        "chance": 100, 
        "name": "of Resist Lightning"
      }, 
      {
        "weighting": 7, 
        "chance": 100, 
        "name": "of Resist Cold"
      }, 
      {
        "weighting": 4, 
        "chance": 100, 
        "name": "of Durability"
      }, 
      {
        "weighting": 2, 
        "chance": 100, 
        "name": "Reinforced"
      }
    ], 
    "index": 1, 
    "name": "of Resistance", 
    "allocations": [
      {
        "minDepth": 25, 
        "itemType": { "shield": "all", "soft armour": "all", "hard armour": "all"},
        "maxDepth": -1
      }
    ], 
    "position": "suffix"
  },

terrain.txt

A list of terrain dicts:

  • a name string
  • a dict of display info
  • a list of interactions dicts (procs which respond to attempted interactions)
  • a list of flags (OBSTRUCT) 
{"name": "granite wall", 
"display": {"ascii": {"color": "L_SLATE", "symbol": "#"}}, 
"interactions": [{"action": "tunnel", "procs": [{"difficulty": 2, "name": "tunnel"}]}],
"flags": ["OBSTRUCT"]},

Not yet existing

monster flags, gf_ types, monster blows, monster spells, player flags

Not sure if these will be necessary now. All the details can be put in effects.txt using the proc system, so there's no need to replicate v4's list-gf-types.h, for example. When defining an effect such as an acid attack, you specify in that effect what resists it or is immune etc.

N.B. We need to agree how to deal with timed effects. My assumption is that these will be done in effects.txt where the relevant flag will be applied for the specified time and then removed at the end. So no separate TMD_ flags. Please!

artifact.txt

The artifacts.

Other angband data files not yet considered: hints.txt, limits.txt, names.txt, pain.txt, p_hist.txt, pit.txt, room_template.txt, shop_own.txt, spell.txt, store.txt, trap.txt, vault.txt

Updated